diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 323a487..2e58a42 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -11,10 +11,13 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  # Static analysis: shellcheck every shell script. The `error` severity gate
-  # is a hard failure (the repo is clean at this level today). Warnings are
-  # reported separately and do not fail the build, so they can be cleaned up
-  # incrementally without blocking merges.
+  # Static analysis: shellcheck every shell script. The repo is clean at both
+  # `error` and `warning` severity, so both are hard gates -- this ratchets the
+  # warning count at zero, preventing warnings from silently accumulating.
+  # Genuinely-unavoidable findings are silenced locally with a `# shellcheck
+  # disable=SCxxxx` directive (with a justification) rather than by lowering the
+  # gate. The test jobs `needs: shellcheck`, so a lint failure short-circuits the
+  # (more expensive) matrix instead of running it in parallel regardless.
   shellcheck:
     name: ShellCheck
     runs-on: ubuntu-latest
@@ -24,25 +27,19 @@ jobs:
       - name: Install shellcheck
         run: sudo apt-get update && sudo apt-get install -y shellcheck
 
-      - name: Collect shell scripts
-        id: collect
+      - name: ShellCheck (warning severity, blocking)
         run: |
           # ell and the launcher have no .sh extension; include them explicitly.
-          files="$(git ls-files '*.sh' 'ell' | tr '\n' ' ')"
-          echo "files=${files}" >> "${GITHUB_OUTPUT}"
-          echo "Scripts to check: ${files}"
-
-      - name: ShellCheck (errors, blocking)
-        run: shellcheck -S error ${{ steps.collect.outputs.files }}
-
-      - name: ShellCheck (warnings, non-blocking)
-        continue-on-error: true
-        run: shellcheck -S warning ${{ steps.collect.outputs.files }}
+          # Use NUL-delimited paths piped to xargs -0 so filenames containing
+          # spaces or newlines are handled correctly (rather than word-splitting
+          # an unquoted, space-joined list).
+          git ls-files -z '*.sh' 'ell' | xargs -0 shellcheck -S warning
 
   # Run the full test suite across the oldest and current supported bash
   # versions using the project's own containerised entry point.
   tests:
     name: Tests (bash ${{ matrix.bash }})
+    needs: shellcheck
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -57,3 +54,132 @@ jobs:
       # curl and a global launcher, so no extra setup is needed here.
       - name: Run test suite
         run: bash tests/entry.sh
+
+  # Run the suite with mawk as `awk`. Debian/Ubuntu default to mawk (not the
+  # gawk/busybox awk the container jobs use), and render_to_text.awk is written
+  # to be portable across awk implementations -- this actually exercises that.
+  tests-mawk:
+    name: Tests (mawk)
+    needs: shellcheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install mawk and make it the default awk
+        run: |
+          sudo apt-get update && sudo apt-get install -y mawk
+          # Point /usr/bin/awk at mawk for this run.
+          sudo update-alternatives --set awk /usr/bin/mawk
+          awk -W version 2>&1 | head -1 || awk --version 2>&1 | head -1 || true
+
+      - name: Run test suite
+        run: bash tests/entry.sh
+
+  # Run the suite on macOS to exercise the BSD toolchain (BSD awk/sed/stat/
+  # mktemp, macOS curl) the code is written to support. macOS ships bash 3.2,
+  # which ell rejects, so install a supported bash; GNU `timeout` is absent on
+  # BSD, so provide it from coreutils (as gtimeout) for the test harness.
+  tests-macos:
+    name: Tests (macOS / BSD tools)
+    needs: shellcheck
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install bash and coreutils (for timeout)
+        run: |
+          brew install bash coreutils
+          # Expose gtimeout as `timeout` for the test harness, on PATH ahead of
+          # anything else. The suite otherwise uses the system BSD tools.
+          mkdir -p "${HOME}/bin"
+          ln -sf "$(brew --prefix coreutils)/libexec/gnubin/timeout" "${HOME}/bin/timeout"
+          echo "${HOME}/bin" >> "${GITHUB_PATH}"
+          # Put the newer bash ahead of the system 3.2.
+          echo "$(brew --prefix)/bin" >> "${GITHUB_PATH}"
+
+      - name: Show tool versions
+        run: |
+          bash --version | head -1
+          command -v timeout && timeout --version | head -1
+          awk --version 2>/dev/null | head -1 || echo "awk: BSD (no --version)"
+
+      - name: Run test suite
+        run: bash tests/entry.sh
+
+  # Run the suite on Windows under a real MSYS2 environment (not Git Bash).
+  # MSYS2 provides a fuller POSIX runtime than Git Bash -- consistent msys-2.0
+  # runtime, ACL-backed permissions, real symlinks, and util-linux (script) --
+  # so more of the suite is expected to work here than under Git Bash. Tools are
+  # installed via pacman. This is currently informational (continue-on-error)
+  # until it is proven stable, then it can become a hard gate.
+  tests-msys2:
+    name: Tests (Windows / MSYS2)
+    needs: shellcheck
+    runs-on: windows-latest
+    continue-on-error: true
+    defaults:
+      run:
+        shell: msys2 {0}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up MSYS2
+        uses: msys2/setup-msys2@v2
+        with:
+          msystem: MSYS
+          update: true
+          # bash comes with MSYS2; add the tools the suite uses. coreutils
+          # provides `timeout`; util-linux provides `script` for record tests;
+          # python is used by the real-PTY record test. 
+          install: >-
+            bash
+            coreutils
+            curl
+            gawk
+            sed
+            grep
+            util-linux
+            python
+
+      - name: Show tool versions
+        run: |
+          bash --version | head -1
+          command -v timeout && timeout --version | head -1
+          command -v script && echo "script: present"
+          awk --version 2>/dev/null | head -1 || true
+
+      - name: Run test suite
+        run: bash tests/entry.sh
+
+  # Run the suite on Windows under Git Bash (the default `shell: bash` on the
+  # windows runner). Git Bash is a deliberately limited environment: over NTFS
+  # it cannot create genuinely group/world-writable files or (by default) real
+  # symlinks, and it ships no `script`. Tests that depend on those capabilities
+  # detect the limitation at runtime and SKIP (see docs/Configuration.md,
+  # "Windows"); for a fuller POSIX environment use the tests-msys2 job above.
+  # This job stays informational: it reports what works rather than blocking.
+  tests-windows:
+    name: Tests (Windows / Git Bash, informational)
+    needs: shellcheck
+    runs-on: windows-latest
+    continue-on-error: true
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Show environment
+        run: |
+          bash --version | head -1
+          uname -a || true
+          for t in curl awk sed stat mktemp script stty tty date chmod; do
+            if command -v "${t}" >/dev/null 2>&1; then
+              printf '%-8s %s\n' "${t}" "$(command -v "${t}")"
+            else
+              printf '%-8s MISSING\n' "${t}"
+            fi
+          done
+
+      - name: Run test suite
+        run: bash tests/entry.sh
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..0a3797a
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,101 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+This is a large hardening pass focused on security, robustness, and testing.
+
+### Security
+
+- Templates are no longer rendered through the shell. Previously template
+  contents were run through `eval`, so a template (or a prompt / recorded
+  context interpolated into one) could execute arbitrary commands. Rendering is
+  now a strict allowlist substitution with JSON escaping and no shell
+  evaluation.
+- `-O KEY=VALUE` no longer runs through `eval`. It is assigned directly and the
+  key is validated, closing a command-injection hole (`-O 'X=$(cmd)'`).
+  Note: as a consequence of the safe, allowlist-only template renderer, variables
+  set via `-O` are exported into the environment but are **no longer substituted
+  into templates** (the old `eval` renderer did expand them). Only the fixed
+  placeholder allowlist is rendered.
+- Config files are only sourced when trusted: owned by the current user (or
+  root) and not group-/world-writable. This blocks the "hostile `.ellrc` in the
+  current directory" arbitrary-code-execution vector. Refusals are now reported
+  at a visible log level.
+- `ELL_API_STYLE` and template names are validated as single path segments, so
+  they cannot be used to source/load arbitrary files by path traversal.
+- The recorded terminal context (`SHELL_CONTEXT`) now passes through the
+  `post_input` hooks, so redaction applies to it too, not just the prompt.
+- The API key is kept out of the process table: it is passed to curl via a
+  `--config` file (mode 0600, removed after use) instead of a `--header`
+  argument, and it is no longer logged at debug level.
+- ell refuses to send credentials to a plaintext `http://` URL (loopback
+  excepted); override with `ELL_ALLOW_INSECURE_URL=true`.
+- The bundled redaction plugin now ships **disabled by default** (its hook has a
+  `.disabled` suffix); enable it by removing the suffix.
+
+### Fixed
+
+- Streaming completions that finish abnormally (e.g. `length` / `MAX_TOKENS`)
+  are now detected and reported as failures instead of silent success
+  (openai read the finish reason from the wrong path).
+- A value-taking option given with no argument (e.g. `ell -m`) no longer causes
+  an infinite loop; it exits with a usage error.
+- Interactive mode exits cleanly on EOF (Ctrl-D) instead of looping forever, and
+  a final unterminated line is still processed. The exit hint now names Ctrl-D.
+- `-o`/`--output` is accepted as documented (previously only `--output-file`),
+  and output is no longer redirected to a file in record/interactive mode (an
+  always-true comparison was fixed).
+- The `--record` "already enabled" guard now works, and `ELL_RECORD` is
+  exported like the other flags.
+- Record mode re-execs ell by an absolute, shell-quoted path, so it works when
+  ell is run in place or is not on `PATH`.
+- Template resolution rejects path-traversal names and accepts an
+  `ELL_TEMPLATE_PATH` with or without a trailing slash; plugin-hook discovery no
+  longer breaks on paths containing spaces/newlines.
+- Missing `ELL_API_URL` now fails early with a clear, actionable message
+  (EX_CONFIG) instead of an opaque curl error; a missing `ELL_API_KEY` warns.
+- curl failures are reported with a human-readable explanation (DNS, connection
+  refused, timeout, TLS, …) rather than a bare exit code.
+- Functions are exported with `export -f` rather than as empty variables.
+- Bash 4.1 compatibility is restored (the version gate, docs and CI now
+  consistently target 4.1).
+
+### Changed
+
+- HTTP requests go through a shared `ell_curl` wrapper with connection/overall
+  timeouts (`ELL_CONNECT_TIMEOUT`, `ELL_MAX_TIME`) and HTTP error handling
+  (`--fail-with-body`), so a stalled server no longer hangs and a 4xx/5xx no
+  longer surfaces as a vague "Unexpected format".
+- The openai and gemini backends share their non-streaming path, end-of-stream
+  reporting and PIPESTATUS handling via `helpers/backend_common.sh`; each keeps
+  only its provider-specific streaming parser.
+- `helpers/http.sh` moved out of `llm_backends/` for consistency with the other
+  helpers.
+- The default log level is unified across entry points.
+
+### Performance
+
+- The pure-bash JSON parser copies runs of ordinary string characters in one
+  operation and no longer forks a subshell per key lookup.
+- The gemini streaming parser tracks JSON object boundaries instead of
+  re-parsing the whole accumulated buffer per line (was O(n²)).
+- Streaming loops use bash builtins instead of a `grep`/`cut`/`tr` subprocess
+  per line, and logging no longer forks `date`/`basename` per line.
+
+### Added
+
+- Documentation: `docs/Architecture.md`, `docs/Backends.md`, expanded
+  `docs/Templates.md` and `docs/Risk_Consideration.md`, and this changelog.
+- Extensive test coverage: unit tests for argument parsing, config loading, path
+  resolution, the HTTP helper, template rendering, the JSON parser, logging, the
+  syntax-highlight and paginator plugins; and end-to-end tests for the request
+  pipeline, hook stages, interactive mode, output redirection, error paths, the
+  launcher, record mode, the bash version gate and terminal-size fallback.
+
+## [0.1.1]
+
+- Baseline release prior to the hardening pass above.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..dfe353c
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,125 @@
+# Contributing
+
+Contributions are welcome — issues, suggestions, and pull requests. This guide
+covers the coding conventions and the test suite. For how the code is
+organised, see [docs/Architecture.md](docs/Architecture.md).
+
+## Coding conventions
+
+ell is deliberately dependency-light bash. A few conventions keep it portable,
+fast, and consistent; please follow them:
+
+- **Portability: bash >= 4.1, GNU *and* BSD tools.** The code runs on Linux and
+  macOS and under `set -o posix` in the test harness. Avoid bashisms that break
+  on 4.1 (e.g. process substitution `< <(...)` under `set -o posix` — use a
+  here-string instead), and prefer POSIX-portable tool invocations (`stat`
+  already falls back from GNU to BSD form).
+- **No per-line subprocesses on hot paths.** Streaming loops and logging must
+  not fork `grep`/`cut`/`tr`/`sed`/`date`/`basename` per line/chunk; use bash
+  builtins (parameter expansion, `[[ ]]`, `printf -v`, `printf '%(...)T'`).
+- **Prefer builtins over external tools** generally, and keep the runtime
+  dependency surface small (bash, curl, awk).
+- **Quoting and comparisons.** Quote expansions. Use the portable
+  `[ "x${VAR}" = "xVALUE" ]` idiom for string comparisons (the `x` prefix guards
+  against values that look like operators); reserve `[[ ]]` for where it is
+  actually needed (regex `=~`, glob `==`). Use `[ "${n}" -ge N ]` for numbers.
+- **Style.** Trailing semicolons on statements, as in the existing code. Keep
+  functions small; give private helpers an `_ell_`/`_json_`-style prefix and
+  export public functions with `export -f`.
+- **Security first.** Never `eval` user-influenced data. Treat templates,
+  plugins and config as the trust-sensitive surfaces they are (see
+  [docs/Risk_Consideration.md](docs/Risk_Consideration.md)). Keep secrets out of
+  argv and logs.
+- **Run ShellCheck.** `error`-level findings block CI; keep the diff clean of
+  new warnings too.
+
+Every behaviour-changing PR should come with tests, and the full suite must
+pass under both supported bash versions (below).
+
+## Testing
+
+The tests are self-checking Bash scripts: each asserts expected values and
+exits non-zero on any failure, so they can gate CI without human inspection.
+They use a tiny built-in assertion helper (`tests/assert.sh`) rather than an
+external framework, keeping the project dependency-free. The LLM backends are
+exercised offline via the `ell_echo` dummy backend and `file://` JSON fixtures,
+so no network or API key is required.
+
+### Layout
+
+Tests come in two flavours:
+
+- **Unit tests live next to the source they cover**, named `<source>.test.sh`,
+  so a file's tests are easy to find right beside it:
+
+  ```
+  helpers/json.sh                        helpers/json.test.sh
+  helpers/logging.sh                     helpers/logging.test.sh
+  helpers/piping.sh                      helpers/piping.test.sh
+  helpers/render_to_text.awk             helpers/render_to_text.test.sh
+  plugins/redaction/50_post_input.sh     plugins/redaction/50_post_input.test.sh
+  ```
+
+- **End-to-end tests that drive the whole `ell` pipeline** (and their JSON
+  fixtures) live in `tests/`, alongside the shared assertion helper
+  `tests/assert.sh`.
+
+### Running
+
+Run the whole suite once, on your host:
+
+```bash
+bash tests/entry.sh
+```
+
+Or run it against the oldest and current supported Bash versions in Docker:
+
+```bash
+bash tests/docker.sh
+```
+
+`tests/entry.sh` auto-discovers every `*.test.sh` in the repository and then
+runs the end-to-end tests. `docker.sh` runs it inside `bash:4.1` and `bash:5.2`
+containers and fails if the suite fails under either version.
+
+### Continuous integration
+
+`.github/workflows/ci.yml` runs on every push and pull request:
+
+- **ShellCheck** over all shell scripts, run at `-S warning`. Both `error` and
+  `warning` findings block the build: the repo is clean at warning severity, so
+  the gate ratchets the warning count at zero to prevent warnings from silently
+  accumulating. Unavoidable findings are silenced locally with a justified
+  `# shellcheck disable=SCxxxx` directive rather than by lowering the gate.
+- **Tests** across a `bash:4.1` and `bash:5.2` container matrix.
+- **Tests (mawk)** with mawk as the default `awk`, exercising the portable
+  `render_to_text.awk`.
+- **Tests (macOS / BSD tools)** on `macos-latest`, exercising the BSD toolchain
+  (BSD awk/sed/stat/mktemp, macOS curl).
+- **Tests (Windows / Git Bash, informational)** on `windows-latest`, which is
+  `continue-on-error` and never blocks the build; it reports what works under
+  Git Bash rather than gating on it.
+
+### Adding a test
+
+For a unit test, create `<source>.test.sh` next to the file it covers, source
+the assertion helper (via a path relative to that location), write assertions,
+and end with `assert_summary`. It is picked up automatically by `entry.sh` —
+no registration needed:
+
+```bash
+#!/usr/bin/env bash
+set -o posix;
+DIR="$(dirname "${0}")";
+# From helpers/ this is ../tests/assert.sh; adjust the depth for other dirs.
+. "${DIR}/../tests/assert.sh";
+. "${DIR}/my_helper.sh";
+
+assert_equals "adds up" "3" "$((1 + 2))";
+
+assert_summary;
+```
+
+End-to-end tests that need JSON fixtures or the full pipeline go in `tests/`
+(sourcing `"${DIR}/assert.sh"`) and are registered with an explicit
+`run_test tests/<name>.sh` line in `tests/entry.sh`.
diff --git a/README.md b/README.md
index 463c3cd..bc0ca21 100644
--- a/README.md
+++ b/README.md
@@ -65,6 +65,25 @@ unless Developer Mode or administrator rights are available. No extra setup is
 required; clone the repository and add its directory to your `PATH` as shown
 above. You invoke it the same way, e.g. `ell "your prompt"`.
 
+**Environment differences and limitations.** The Bash environments differ in how
+faithfully they emulate a POSIX system, and a few features degrade accordingly:
+
+- **WSL** behaves like Linux; everything works.
+- **MSYS2** and **Cygwin** provide a fairly complete POSIX layer (ACL-backed
+  file permissions, real symbolic links, `script(1)`), so the whole feature set
+  works.
+- **Git Bash** is intentionally minimal. Over NTFS it cannot create genuinely
+  group/world-writable files, so the config-file permission check in
+  `load_config` (which refuses to source a world-writable `.ellrc`) and the
+  `chmod 600` on the temporary auth-header file **cannot be enforced**; it also
+  lacks `script(1)` (record mode) and, by default, real symlinks. ell still
+  runs, but on a multi-user machine treat these as **security limitations** —
+  see [Configuration → Windows](docs/Configuration.md#windows) for details and
+  the safer alternatives (MSYS2 / WSL).
+
+For the most complete experience on Windows, prefer **WSL** or **MSYS2** over
+Git Bash.
+
 ## Configuration
 
 See [Configuration](docs/Configuration.md).
@@ -165,6 +184,20 @@ See [Plugins](docs/Plugins.md).
 
 The term "Plugin" here means a script that can be called by ell. It can be used to extend ell's functionality. The plugins supported by LLM providers is not included here. Please refer to [Templates](docs/Templates.md).
 
+## Backends
+
+See [Backends](docs/Backends.md).
+
+A backend adapts ell to an LLM API "style" (selected with `--api-style` /
+`ELL_API_STYLE`). OpenAI and Gemini are supported out of the box, and you can
+add your own.
+
+## Architecture
+
+See [Architecture](docs/Architecture.md) for how ell is put together: the
+startup sequence, configuration precedence, the request pipeline and its four
+hook stages, backends, and record mode.
+
 ## Risks to consider
 
 See [Risks Consideration](docs/Risk_Consideration.md).
@@ -199,86 +232,21 @@ See [Risks Consideration](docs/Risk_Consideration.md).
 
 ## Testing
 
-The tests are self-checking Bash scripts: each asserts expected values and
-exits non-zero on any failure, so they can gate CI without human inspection.
-They use a tiny built-in assertion helper (`tests/assert.sh`) rather than an
-external framework, keeping the project dependency-free. The LLM backends are
-exercised offline via the `ell_echo` dummy backend and `file://` JSON fixtures,
-so no network or API key is required.
-
-### Layout
-
-Tests come in two flavours:
-
-- **Unit tests live next to the source they cover**, named `<source>.test.sh`,
-  so a file's tests are easy to find right beside it:
-
-  ```
-  helpers/json.sh                        helpers/json.test.sh
-  helpers/logging.sh                     helpers/logging.test.sh
-  helpers/piping.sh                      helpers/piping.test.sh
-  helpers/render_to_text.awk             helpers/render_to_text.test.sh
-  plugins/redaction/50_post_input.sh     plugins/redaction/50_post_input.test.sh
-  ```
-
-- **End-to-end tests that drive the whole `ell` pipeline** (and their JSON
-  fixtures) live in `tests/`: `tests/templating.sh` and `tests/parse_output.sh`,
-  alongside the shared assertion helper `tests/assert.sh`.
-
-### Running
-
-Run the whole suite once, on your host:
-
-```bash
-bash tests/entry.sh
-```
-
-Or run it against the oldest and current supported Bash versions in Docker:
-
-```bash
-bash tests/docker.sh
-```
-
-`tests/entry.sh` auto-discovers every `*.test.sh` in the repository and then
-runs the end-to-end tests. `docker.sh` runs it inside `bash:4.1` and `bash:5.2`
-containers and fails if the suite fails under either version.
-
-### Continuous integration
-
-`.github/workflows/ci.yml` runs on every push and pull request:
-
-- **ShellCheck** over all shell scripts. Findings at `error` severity block the
-  build; warnings are reported but non-blocking so they can be cleaned up
-  incrementally.
-- **Tests** across a `bash:4.1` and `bash:5.2` matrix.
+Run the whole suite on your host with `bash tests/entry.sh`, or across the
+supported Bash versions in Docker with `bash tests/docker.sh`. The tests are
+self-checking and dependency-free (the LLM backends are exercised offline via
+the `ell_echo` backend and `file://` fixtures, so no network or API key is
+needed). See [CONTRIBUTING.md](CONTRIBUTING.md) for the layout and how to add a
+test.
 
-### Adding a test
-
-For a unit test, create `<source>.test.sh` next to the file it covers, source
-the assertion helper (via a path relative to that location), write assertions,
-and end with `assert_summary`. It is picked up automatically by `entry.sh` —
-no registration needed:
-
-```bash
-#!/usr/bin/env bash
-set -o posix;
-DIR="$(dirname "${0}")";
-# From helpers/ this is ../tests/assert.sh; adjust the depth for other dirs.
-. "${DIR}/../tests/assert.sh";
-. "${DIR}/my_helper.sh";
-
-assert_equals "adds up" "3" "$((1 + 2))";
-
-assert_summary;
-```
+## Contributing
 
-End-to-end tests that need JSON fixtures or the full pipeline go in `tests/`
-(sourcing `"${DIR}/assert.sh"`) and are registered with an explicit
-`run_test tests/<name>.sh` line in `tests/entry.sh`.
+Contributions are welcome! Please open an issue or submit a pull request. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for coding conventions and the test suite.
 
-## Contributing
+## Changelog
 
-Contributions are welcome! If you have any ideas, suggestions, or bug reports, please open an issue or submit a pull request.
+See [CHANGELOG.md](CHANGELOG.md) for notable changes.
 
 ## License
 
diff --git a/docs/Architecture.md b/docs/Architecture.md
new file mode 100644
index 0000000..1d2b373
--- /dev/null
+++ b/docs/Architecture.md
@@ -0,0 +1,129 @@
+# Architecture
+
+ell is a small, dependency-light bash program: an entrypoint (`ell.sh`), a set
+of sourced helpers under `helpers/`, pluggable LLM backends under
+`llm_backends/`, and user plugins discovered across several search roots. This
+document explains how the pieces fit together.
+
+## Entry points
+
+- **`ell`** — a thin launcher. It resolves its own directory (following
+  symlinks) and execs `ell.sh`, so the bundled helpers/templates are found no
+  matter how ell was invoked (in place, on `PATH`, or via a symlink in
+  `~/.local/bin`).
+- **`ell.sh`** — the orchestrator. It checks the bash version, sources the
+  helpers and the selected backend, loads configuration, parses arguments,
+  builds a request from a template, runs it through the backend, and applies
+  plugin hooks around each stage.
+
+## Startup sequence (`ell.sh`)
+
+1. **bash version gate** — require bash >= 4.1.
+2. **Resolve `BASE_DIR`** to an absolute path (needed because record mode
+   re-execs ell from a different working directory).
+3. **Source helpers** (`helpers/*.sh`) and then the backend dispatcher.
+4. **`load_config`** — layer configuration (see below).
+5. **Apply defaults** for any `ELL_*` still unset.
+6. **`parse_arguments`** — command-line flags override everything.
+7. **Preflight** — for a network backend, require `ELL_API_URL` (fatal if
+   missing) and warn if `ELL_API_KEY` is unset.
+8. **Decide output** — redirect stdout to `ELL_OUTPUT_FILE` (plain mode only),
+   detect TTY, read terminal size.
+9. **Decorate `generate_completion`** with the pre/post-LLM hooks.
+10. **Record mode** (optional) — re-exec ell under `script` to capture the
+    session (see below).
+11. **Resolve the template**, optionally read the prompt from a file.
+12. **Build and send the request**, once (one-shot) or in a loop (interactive).
+
+## Configuration precedence
+
+`load_config` layers configuration so that later sources win, while never
+overriding a variable already set in the environment:
+
+1. built-in defaults (in `ell.sh`)
+2. config files, in order: XDG config, `~/.ellrc`, `$PWD/.ellrc`, `$ELL_CONFIG`
+3. environment variables
+4. command-line arguments (highest priority)
+
+Config files are *sourced* (executed), so `load_config` only sources a file
+owned by the current user (or root) and not group-/world-writable. See
+[Configuration](Configuration.md) and [Risk Consideration](Risk_Consideration.md).
+
+## The request pipeline and hook stages
+
+A prompt flows through four hook stages. Each stage runs every plugin hook of
+that kind (discovered across the search roots) as a pipeline via `piping`:
+
+```mermaid
+flowchart TD
+    P["USER_PROMPT"]
+    RT["render_template<br/><i>(build JSON payload)</i>"]
+    B["backend<br/><i>generate_completion (LLM)</i>"]
+    OUT["stdout"]
+
+    P -->|"post_input hook<br/>(redaction)"| RT
+    RT -->|"pre_llm hook<br/>(transform payload)"| B
+    B -->|"post_llm hook<br/>(transform response)"| M(["response text"])
+    M -->|"pre_output hook<br/>(paginate, highlight)"| OUT
+```
+
+- **`post_input`** — transforms `USER_PROMPT` (and the recorded
+  `SHELL_CONTEXT`) *before* it is substituted into the template. This is where
+  redaction runs, so secrets are scrubbed before anything is sent.
+- **`render_template`** — substitutes the allowlisted `${VAR}` placeholders into
+  the JSON template, JSON-escaping string values. Templates are treated as data
+  and never shell-evaluated. See [Templates](Templates.md).
+- **`pre_llm`** — transforms the request payload before it reaches the backend.
+- **backend** — `generate_completion` sends the payload and prints the
+  completion text. See [Backends](Backends.md).
+- **`post_llm`** — transforms the backend's response.
+- **`pre_output`** — transforms the final text before it is written to stdout
+  (pagination, syntax highlighting).
+
+The decoration in `ell.sh` renames the backend's `generate_completion` to
+`orig_generate_completion` and wraps it so that `pre_llm | orig_generate_completion
+| post_llm` runs as one pipeline, with the backend's exit status (not the last
+hook's) propagated.
+
+Hooks are shell scripts named `<NN>_<stage>.sh` (e.g. `50_post_input.sh`) under
+`plugins/<name>/` in any search root; a hook whose filename contains `.disabled`
+is skipped. See [Plugins](Plugins.md).
+
+## Backends
+
+`ELL_API_STYLE` selects `llm_backends/<style>/generate_completion.sh`, which is
+sourced and must define `generate_completion` (stdin = request body, stdout =
+completion text, exit code = status). `helpers/backend_common.sh` holds the
+non-streaming path, end-of-stream reporting, and PIPESTATUS handling shared by
+the bundled backends; each backend keeps only its provider-specific streaming
+parser. See [Backends](Backends.md).
+
+## Record mode
+
+When recording (or interactive) is requested, ell re-execs itself under
+`script(1)` so the whole session is captured to a log, and the tail of that log
+is fed back as `SHELL_CONTEXT` on subsequent turns. The re-exec uses an
+absolute, shell-quoted path to the `ell` launcher so it does not depend on ell
+being on `PATH`.
+
+## Helpers (`helpers/`)
+
+| File | Responsibility |
+|------|----------------|
+| `logging.sh` | Leveled logging to stderr (`logging_debug`…`logging_fatal`). |
+| `parse_arguments.sh` | CLI flag parsing and usage/version output. |
+| `load_config.sh` | Layered, trust-checked configuration loading. |
+| `piping.sh` | Run a list of hook scripts as a pipeline. |
+| `json.sh` | Pure-bash JSON parser (`json_parse`/`json_get`/`json_has`), no `jq`. |
+| `resolve_paths.sh` | Discover templates and plugin hooks across search roots. |
+| `render_template.sh` | Safe allowlist template rendering + JSON escaping. |
+| `http.sh` | `ell_curl` wrapper: timeouts, HTTP errors, off-argv credentials. |
+| `backend_common.sh` | Shared non-streaming / reporting / PIPESTATUS logic. |
+| `render_to_text.awk` | Render recorded terminal output to plain text. |
+
+## Testing
+
+Unit tests live next to their source as `<name>.test.sh` and are
+auto-discovered; end-to-end tests that drive the whole `ell` pipeline live in
+`tests/`. `tests/entry.sh` runs everything; `tests/docker.sh` runs it across
+bash versions. See the README's testing section (and CONTRIBUTING.md).
diff --git a/docs/Backends.md b/docs/Backends.md
new file mode 100644
index 0000000..15ed73e
--- /dev/null
+++ b/docs/Backends.md
@@ -0,0 +1,92 @@
+# Backends
+
+A backend adapts ell to one LLM HTTP API "style". The backend to use is
+selected by `ELL_API_STYLE` (or `--api-style`), defaulting to `openai`. For how
+backends fit into the overall request pipeline, see
+[Architecture](Architecture.md).
+
+## Built-in backends
+
+| `ELL_API_STYLE` | API | Notes |
+|-----------------|-----|-------|
+| `openai`  | OpenAI-compatible chat completions | default; use `default-openai` template |
+| `gemini`  | Google Gemini (v1beta)             | use `default-gemini` template |
+| `ell_echo`| none — echoes the request body     | for debugging/testing; no network |
+
+The `ell_echo` backend simply writes the request payload it received to stdout,
+which makes it handy for inspecting exactly what a template produced.
+
+## How dispatch works
+
+`ELL_API_STYLE` selects a directory under `llm_backends/`:
+
+```
+llm_backends/${ELL_API_STYLE}/generate_completion.sh
+```
+
+That file is sourced and must define a shell function `generate_completion`.
+`ELL_API_STYLE` is validated to a single path segment (`[A-Za-z0-9._-]`, not
+`.`/`..`), so it cannot be used to source an arbitrary file by path traversal;
+an unknown style is a fatal error.
+
+## The `generate_completion` contract
+
+`generate_completion` is invoked as a pipeline stage:
+
+- **stdin**: the JSON request body ell built from the template.
+- **stdout**: the assistant's text completion (only the text, no JSON).
+- **stderr**: diagnostics and usage logging (via the `logging_*` helpers).
+- **exit status**: `0` on success; non-zero on failure. The bundled backends
+  use these distinct codes, and ell propagates them:
+  - `3` — the response contained no usable content (empty/unparsable).
+  - `4` — the completion finished abnormally (e.g. truncated: `length` /
+    `MAX_TOKENS`, or a content filter), so it must not be reported as success.
+  - the curl exit code — a transport failure (propagated as-is).
+
+Backends honour `ELL_API_STREAM` (`true`/`false`) to choose between a streaming
+and a single-response request.
+
+## HTTP requests: use `ell_curl`
+
+Backends should make requests through `ell_curl` (in `helpers/http.sh`)
+rather than calling `curl` directly, so they inherit ell's shared behaviour:
+
+- connection/overall timeouts (`ELL_CONNECT_TIMEOUT`, `ELL_MAX_TIME`);
+- HTTP error handling (`--fail-with-body` / `--fail`), so a 4xx/5xx becomes a
+  non-zero exit instead of a silent empty body;
+- credentials kept off the command line: set `ELL_CURL_AUTH_HEADER` (e.g.
+  `Authorization: Bearer ${ELL_API_KEY}`) and `ell_curl` passes it via a
+  `--config` file, so the key is not visible in `ps` / `/proc`;
+- a refusal to send credentials over plaintext `http://` remotes unless
+  `ELL_ALLOW_INSECURE_URL=true` (see [Risk Consideration](Risk_Consideration.md)).
+
+Pass the request body with `--data-binary @-` so it is read from stdin.
+
+## Writing a custom backend
+
+1. Create `llm_backends/<style>/generate_completion.sh` (under any of the search
+   roots — your XDG config dir works too).
+2. Define `generate_completion`. The helpers (`ell_curl`, `json_*`,
+   `logging_*`) are already sourced by ell before your backend, so you do not
+   source them yourself:
+
+   ```bash
+   #!/usr/bin/env bash
+
+   generate_completion() {
+     local ELL_CURL_AUTH_HEADER="Authorization: Bearer ${ELL_API_KEY}";
+     export ELL_CURL_AUTH_HEADER;
+     # Read the JSON body from stdin, call the API, print the text to stdout.
+     ell_curl "${ELL_API_URL}" \
+       --header "Content-Type: application/json" \
+       --data-binary @- \
+       | # ...parse the response (see helpers/json.sh) and print the text...
+   }
+   export -f generate_completion;
+   ```
+
+3. Add a matching template (see [Templates](Templates.md)) and select the
+   backend with `--api-style <style>` (or `ELL_API_STYLE`).
+
+Parse responses with the bundled pure-bash JSON helpers in `helpers/json.sh`
+(`json_parse`, `json_get`, `json_has`) so no external `jq` dependency is needed.
diff --git a/docs/Configuration.md b/docs/Configuration.md
index 2042811..116ed57 100644
--- a/docs/Configuration.md
+++ b/docs/Configuration.md
@@ -24,7 +24,7 @@ If you are running ell in a relatively hostile environment, it is recommended to
 
 The following variables can be set in the configuration files, environment variables:
 
-- `ELL_LOG_LEVEL`: The log level of the logger. The default is `2`. A log level of `0` will log everything. A log level of `3` will log token usage.
+- `ELL_LOG_LEVEL`: The verbosity of the logger, from `1` (least) to `5` (most). The default is `2`. Higher values enable more output: `1` = fatal only, `2` = errors (default), `3` = warnings, `4` = info (this is the level at which token usage is logged), `5` = debug (everything). A value of `0` disables all logging.
 - `ELL_CONFIG`: An extra configuration file to load, applied last (highest precedence among files). Unset by default. The standard config files (`${XDG_CONFIG_HOME:-$HOME/.config}/ell/config`, `~/.ellrc`, `./.ellrc`) are always read regardless of this variable.
 - `ELL_LLM_MODEL`: The model to use. Default is `gpt-4o-mini`.
 - `ELL_LLM_TEMPERATURE`: The temperature of the model. The default is `0.6`.
@@ -41,11 +41,12 @@ The following variables can be set in the configuration files, environment varia
 - `ELL_API_STREAM`: Whether to stream the output. The default is `true`.
 - Plugins related variables:
   - `TO_TTY`: Force ell to output with syntax highlighting and pagination or not. 
-  - Styling related variables can be found in [Styling](docs/Styling.md).
+  - Styling related variables can be found in [Styling](Styling.md).
 
-The following variables can be set in the command line arguments:
-  -h, --help: show this help
+The following can be set in the command line arguments:
 
+- `-h, --help`: show this help and exit.
+- `-V, --version`: show the version and exit.
 - `-l, --log-level`: `ELL_LOG_LEVEL`
 - `-m, --model`: `ELL_LLM_MODEL`
 - `-T, --template-path`: `ELL_TEMPLATE_PATH`
@@ -53,12 +54,55 @@ The following variables can be set in the command line arguments:
 - `-f, --input-file`: `ELL_INPUT_FILE`
 - `-r, --record`: sets `ELL_RECORD` to true. This will ignore the prompt input or the file input.
 - `-i, --interactive`: `ELL_INTERACTIVE`.  This will ignore the prompt input or the file input.
-- `-o, --output-file`: `ELL_OUTPUT_FILE`
+- `-o, --output, --output-file`: `ELL_OUTPUT_FILE`
 - `--api-style`: `ELL_API_STYLE`
 - `--api-key`: `ELL_API_KEY`, note that in multi-user environments, other users are able to see the command line arguments.
 - `--api-url`: `ELL_API_URL`
 - `--api-disable-streaming`: sets `ELL_API_STREAM` to **false**
 - `-c, --config`: `ELL_CONFIG`
-- `-O, --option`: Other options. The format is `A=b` or `C=d,E=f`. They will be accessible in the templates.
+- `-O, --option`: Set extra environment variables for the run. The format is `A=b` or `C=d,E=f`. The key must be a valid shell variable name. These variables are exported into ell's environment (so plugins and backends can read them), but note that **they are not substituted into templates**: the template renderer only substitutes a fixed allowlist of placeholders (see [Templates](Templates.md)). Under the previous `eval`-based renderer arbitrary `-O` variables did appear in templates; that behavior was removed with the switch to safe, allowlist-only rendering.
 
-Currently, only OpenAI and Gemini style API is supported. More API styles are coming soon.
\ No newline at end of file
+OpenAI and Gemini style APIs are supported out of the box (plus an `ell_echo`
+debugging backend). You can add your own — see [Backends](Backends.md).
+
+## Windows
+
+ell runs on Windows from any Bash environment (Git Bash, MSYS2, Cygwin, WSL),
+but these environments emulate a POSIX system to different degrees. Two behaviors
+depend on facilities that **Git Bash does not provide over NTFS**, and they
+degrade there:
+
+### Config file trust check (security limitation)
+
+Config files (`${XDG_CONFIG_HOME:-$HOME/.config}/ell/config`, `~/.ellrc`,
+`$PWD/.ellrc`, `$ELL_CONFIG`) are **sourced**, i.e. executed as shell code. To
+avoid running attacker-controlled code, `load_config` refuses to source a file
+that is not owned by the current user/root or that is writable by group or
+others (see [Risk Consideration](Risk_Consideration.md)).
+
+This check relies on POSIX ownership and permission bits. On **Git Bash** over
+NTFS, `chmod` cannot create genuinely group/world-writable files and `stat` does
+not report reliable permission bits, so **the check cannot distinguish a safe
+config from an insecure one and effectively cannot protect you there**. On a
+shared/multi-user Windows machine, do not rely on this protection under Git Bash;
+use **WSL** or **MSYS2/Cygwin** (which back permissions with NTFS ACLs), or keep
+your config on a volume only you can write.
+
+The temporary file ell uses to pass the API key to `curl` is likewise
+`chmod 600`ed to keep the credential owner-only; that too is not enforceable
+under Git Bash.
+
+### Symbolic links and record mode
+
+- Installing `ell` by **symlink** and record mode's terminal capture
+  (`script(1)`) both require capabilities Git Bash lacks by default (real
+  symlinks need Developer Mode / admin; `script` is not shipped). ell itself is
+  a plain wrapper script, so normal use does not need symlinks; MSYS2 and WSL
+  provide both when you need them.
+
+### Test suite
+
+The test suite detects these limitations at runtime and prints `SKIP:` for the
+affected checks under Git Bash rather than failing, so the informational Windows
+CI run stays meaningful. CI also runs the suite under a fuller **MSYS2**
+environment, where these features are available and the checks run normally.
\ No newline at end of file
diff --git a/docs/Plugins.md b/docs/Plugins.md
index d15bd4b..71aaf2c 100644
--- a/docs/Plugins.md
+++ b/docs/Plugins.md
@@ -3,17 +3,22 @@
 
 The plugin system is designed to enrich the user experience and extend the functionality of ell, while keeping the code modular and flexible.
 
-The term "plugin" here means a script that can be called by ell. It can be used to extend ell's functionality. The plugins supported by LLM providers are not included here. Please refer to [Templates](docs/Templates.md).
+The term "plugin" here means a script that can be called by ell. It can be used to extend ell's functionality. The plugins supported by LLM providers are not included here. Please refer to [Templates](Templates.md).
 
 ## Built-in Plugins
 
 Built-in plugins are available in the `./plugins` directory of the ell repository: 
 
 - **redaction**: Redacts sensitive information.
-- **aginator**: Paginates the output.
+- **paginator**: Paginates the output.
 - **syntax_highlight**: Syntax highlights the output.
 
-The "redaction" plugin is disabled by default. To enable it, remove the `.disabled` extension from the plugin script name.
+The "redaction" plugin is disabled by default because it is a best-effort
+control that can also mangle legitimate input. Its hook script therefore ships
+as `plugins/redaction/50_post_input.sh.disabled`. Any hook script whose name
+contains `.disabled` is ignored by the plugin loader, so to enable redaction
+remove the `.disabled` suffix (rename it back to `50_post_input.sh`); to disable
+any other plugin, add a `.disabled` suffix to its hook script.
 
 ## Writing Plugins
 
diff --git a/docs/Risk_Consideration.md b/docs/Risk_Consideration.md
index ad37a1e..f8a8306 100644
--- a/docs/Risk_Consideration.md
+++ b/docs/Risk_Consideration.md
@@ -2,10 +2,54 @@
 
 The following risks should be considered when using ell:
 
+## Sending data to LLM backends
+
 - The prompts are sent to LLM backends, so be careful with sensitive information.
-  - A redaction plugin ([#14](https://github.com/simonmysun/ell/issues/14)) is available to redact sensitive information, but it is not foolproof. For enhanced desensitization, use your own plugin or call third-party softwares.
-- The output of LLMs is not guaranteed to be correct or safe.
-- In record mode, all your input and output history are written to `/tmp/tmp.xxxx` and are readable by root user. 
-- LLM can be tuned or prompted to return deceptive results, e.g. manipulating your terminal
-- Unexpected exit of record mode may cause the history file to remain in `/tmp/`.
-- Password input is not recorded by `script`, so it is safe to type sudo or ssh passwords in terminal.
\ No newline at end of file
+  - A redaction plugin ([#14](https://github.com/simonmysun/ell/issues/14)) is
+    available to redact sensitive information, but it is not foolproof. For
+    enhanced desensitization, use your own plugin or call third-party softwares.
+    The redaction plugin ships **disabled by default** (its hook script has a
+    `.disabled` suffix); enable it by removing that suffix. See
+    [Plugins](Plugins.md).
+  - In record/interactive mode, the recorded terminal context (`$SHELL_CONTEXT`)
+    is also sent to the backend. It is passed through the same `post_input` hooks
+    as your prompt, so redaction applies to it too when enabled.
+- The output of LLMs is not guaranteed to be correct or safe. An LLM can be
+  tuned or prompted to return deceptive results, e.g. instructions that
+  manipulate your terminal.
+
+## Executable content: templates, plugins and config
+
+ell treats templates, plugins and config files as **code**, not just data.
+Installing them from untrusted sources runs arbitrary commands as your user:
+
+- **Plugins** are shell scripts executed as you. Only install plugins you trust.
+- **Config files** are sourced (executed). ell only sources a config file that
+  is owned by you (or root) and is not group-/world-writable, which blocks the
+  "hostile `.ellrc` in the current directory" attack, but a config file *you*
+  own can still run anything you put in it.
+- **Templates** are substituted with a fixed allowlist of variables and are
+  **not** evaluated by the shell, so a template file cannot execute commands.
+  Values you supply (prompt, model, etc.) are inserted as data. Older, unrelated
+  "install a template" advice from third parties should still be treated with
+  care.
+- `ELL_API_STYLE` and template names are validated so they cannot be used to
+  load arbitrary files by path traversal.
+
+## Credentials
+
+- Passing `--api-key` on the command line is discouraged: it ends up in your
+  shell history. Prefer a config file (with safe permissions) or the
+  environment. The key is not logged and is not placed on curl's command line.
+- By default ell refuses to send credentials to a plaintext `http://` URL (only
+  `https://` and loopback hosts are allowed) to avoid leaking the key in
+  cleartext. Set `ELL_ALLOW_INSECURE_URL=true` to override for a trusted local
+  endpoint.
+
+## Record mode
+
+- In record mode, all your input and output history are written to
+  `/tmp/tmp.xxxx` and are readable by the root user.
+- Unexpected exit of record mode may leave the history file in `/tmp/`.
+- Password input is not recorded by `script`, so it is safe to type sudo or ssh
+  passwords in the terminal.
\ No newline at end of file
diff --git a/docs/Templates.md b/docs/Templates.md
index c6dafa0..86eca72 100644
--- a/docs/Templates.md
+++ b/docs/Templates.md
@@ -2,10 +2,23 @@
 
 Templates are used to generate the payload sent to the language model. They are written in JSON format and can be customized by users. Templates are where you set the prompt text and other parameters for the language model.
 
-Currently, there are two variables that can be used in the templates, except the ones given by users:
+The following variables can be used in templates and are substituted by ell
+when the request payload is built:
 
-- `$SHELL_CONTEXT`: The context of the shell. This only works when the shell is started with `-r` or `--record`.
 - `$USER_PROMPT`: The prompt text given by the user.
+- `$SHELL_CONTEXT`: The recorded terminal context. This is only populated when
+  the session is started with `-r` / `--record` (or in interactive mode).
+- `$ELL_LLM_MODEL`: The model name (e.g. from `-m` / `ELL_LLM_MODEL`).
+- `$ELL_LLM_TEMPERATURE`: The sampling temperature.
+- `$ELL_LLM_MAX_TOKENS`: The maximum number of tokens to generate.
+- `$ELL_API_STREAM`: Whether streaming is enabled (`true`/`false`).
+
+`$USER_PROMPT`, `$SHELL_CONTEXT` and `$ELL_LLM_MODEL` are inserted as JSON
+strings (their values are JSON-escaped), so you must wrap them in double quotes
+in the template. `$ELL_LLM_TEMPERATURE`, `$ELL_LLM_MAX_TOKENS` and
+`$ELL_API_STREAM` are inserted verbatim as JSON numbers/booleans, so they must
+not be quoted. Any other `${...}` sequence is left untouched: template contents
+are treated as data and are never evaluated by the shell.
 
 Here's an example template for openai style API:
 
diff --git a/ell.sh b/ell.sh
index b7ab2bb..2d12319 100755
--- a/ell.sh
+++ b/ell.sh
@@ -3,11 +3,11 @@
 # ${BASH_VERSINFO:-0} is tested first because the BASH_VERSINFO array was introduced in bash-2.0-beta1. I have tested bash-2.05a.0(1)-release and the code below works.
 if [ "${BASH_VERSINFO:-0}" -ge 4 ]; then
   if [ "${BASH_VERSINFO:-0}" -eq 4 ] && [ "${BASH_VERSINFO[1]:-0}" -lt 1 ]; then
-    echo "Bash version 4.2 or higher is required to run this script";
+    echo "Bash version 4.1 or higher is required to run this script";
     exit 69;
   fi
 else
-  echo "Bash version 4.2 or higher is required to run this script";
+  echo "Bash version 4.1 or higher is required to run this script";
   exit 69;
 fi
 
@@ -15,7 +15,14 @@ ELL_VERSION="0.1.1";
 
 : "${ELL_LOG_LEVEL:=2}";
 
-BASE_DIR=$(dirname "${0}");
+# Resolve BASE_DIR to an absolute path. `dirname "${0}"` can be relative (e.g.
+# "." when run as ./ell.sh); record mode re-execs ell via `script -c` in a
+# shell that may have a different working directory, so a relative BASE_DIR
+# would not resolve there. An absolute path is safe everywhere.
+BASE_DIR=$(cd "$(dirname "${0}")" >/dev/null 2>&1 && pwd);
+if [ -z "${BASE_DIR}" ]; then
+  BASE_DIR=$(dirname "${0}");
+fi
 
 # logging_debug "Importing helper functions";
 . "${BASE_DIR}/helpers/logging.sh";
@@ -24,6 +31,9 @@ BASE_DIR=$(dirname "${0}");
 . "${BASE_DIR}/helpers/piping.sh";
 . "${BASE_DIR}/helpers/json.sh";
 . "${BASE_DIR}/helpers/resolve_paths.sh";
+. "${BASE_DIR}/helpers/render_template.sh";
+. "${BASE_DIR}/helpers/http.sh";
+. "${BASE_DIR}/helpers/backend_common.sh";
 
 logging_debug "Starting ${0}";
 
@@ -59,14 +69,37 @@ parse_arguments "${@}";
 
 . "${BASE_DIR}/llm_backends/generate_completion.sh";
 
-# Deciding where to output
-if [ "x${ELL_OUTPUT_FILE}" != "x-" ]; then
-  if [ "${ELL_RECORD}" != "xtrue" ] && [ "${ELL_INTERACTIVE}" != "xtrue" ]; then
-    logging_debug "Outputting to file: ${ELL_OUTPUT_FILE}";
-    exec 1>"${ELL_OUTPUT_FILE}";
+# Preflight the essential API config so a first-run misconfiguration produces a
+# clear, actionable message instead of an opaque curl error later. The ell_echo
+# backend talks to no network, so it needs neither URL nor key.
+if [ "x${ELL_API_STYLE}" != "xell_echo" ]; then
+  if [ -z "${ELL_API_URL}" ]; then
+    logging_fatal "ELL_API_URL is not set. Configure it (e.g. in \$XDG_CONFIG_HOME/ell/config or ~/.ellrc), pass --api-url, or set the ELL_API_URL environment variable. See docs/Configuration.md.";
+    exit 78; # EX_CONFIG
+  fi
+  if [ -z "${ELL_API_KEY}" ]; then
+    # An empty key is valid for some local/proxy endpoints, so warn rather than
+    # fail; the request will still be attempted.
+    logging_warn "ELL_API_KEY is not set; sending the request without an Authorization header. Set --api-key or ELL_API_KEY if your endpoint requires one.";
   fi
 fi
 
+# Deciding where to output. Redirect stdout to ELL_OUTPUT_FILE only when an
+# output file other than "-" was requested AND we are not in record or
+# interactive mode (in those modes stdout must stay on the terminal for the
+# recorded/interactive session).
+#
+# The 'x' prefix must be on both sides of each comparison: ELL_RECORD and
+# ELL_INTERACTIVE hold "true"/"false", never "xtrue", so the previous
+# `"${ELL_RECORD}" != "xtrue"` was always true and the redirect fired even in
+# record/interactive mode.
+if [ "x${ELL_OUTPUT_FILE}" != "x-" ] \
+   && [ "x${ELL_RECORD}" != "xtrue" ] \
+   && [ "x${ELL_INTERACTIVE}" != "xtrue" ]; then
+  logging_debug "Outputting to file: ${ELL_OUTPUT_FILE}";
+  exec 1>"${ELL_OUTPUT_FILE}";
+fi
+
 # logging_debug "Checking if we are outputting to a TTY or not";
 if [ -z "${TO_TTY}" ]; then
   [ -t 1 ] && TO_TTY=true || TO_TTY=false;
@@ -84,13 +117,21 @@ fi
 export PAGE_SIZE;
 export COLUMNS;
 
-# Logging_debug "Decorating the generate_completion to apply hooks before and after";
-eval "$(printf "orig_"; command -V generate_completion | tail -n +2)";
+# Decorate generate_completion to apply the pre/post-LLM hooks around it: copy
+# the backend's definition to orig_generate_completion, then redefine
+# generate_completion as the wrapper below. `declare -f` prints just the
+# function definition (no localizable "is a function" description line), so
+# prefixing its output is cleaner and less fragile than splicing `command -V`.
+eval "orig_$(declare -f generate_completion)";
 generate_completion() {
   local pre_llm_hooks post_llm_hooks backend_status;
-  mapfile -t pre_llm_hooks < <(list_plugin_hooks _pre_llm.sh);
+  # Use a here-string, not process substitution (`< <(...)`): the latter is a
+  # parse error under `set -o posix` on bash 4.1, the oldest version ell
+  # supports (see CONTRIBUTING.md). An empty result yields a single empty
+  # element, which piping() treats as "no pipes" (its `[ "${1}" = '' ]` guard).
+  mapfile -t pre_llm_hooks <<< "$(list_plugin_hooks _pre_llm.sh)";
   logging_debug "Pre LLM hooks: ${pre_llm_hooks[*]}";
-  mapfile -t post_llm_hooks < <(list_plugin_hooks _post_llm.sh);
+  mapfile -t post_llm_hooks <<< "$(list_plugin_hooks _post_llm.sh)";
   logging_debug "Post LLM hooks: ${post_llm_hooks[*]}";
   piping "${pre_llm_hooks[@]}" \
   | orig_generate_completion \
@@ -101,22 +142,50 @@ generate_completion() {
   return "${backend_status}";
 }
 
-# Logging_debug "Checking if we are going to enter record mode";
-if [ "x${ELL_RECORD}" = "xtrue" ] || [ "x${ELL_INTERACTIVE}" = "xtrue" ] && [ "x${ELL_TMP_SHELL_LOG}" != "x-" ] && [ ! -f "${ELL_TMP_SHELL_LOG}" ]; then
+# logging_debug "Checking if we are going to enter record mode";
+# Enter record mode when we are recording OR interactive, AND the shell log is
+# not "-" and does not already exist (i.e. we have not already re-exec'd under
+# `script`). The (record OR interactive) part is grouped explicitly: `&&` and
+# `||` share precedence and left-associate, so without the braces this reads as
+# `((record || interactive) && ...)` -- correct today only by accident, and
+# fragile to edit.
+if { [ "x${ELL_RECORD}" = "xtrue" ] || [ "x${ELL_INTERACTIVE}" = "xtrue" ]; } \
+   && [ "x${ELL_TMP_SHELL_LOG}" != "x-" ] \
+   && [ ! -f "${ELL_TMP_SHELL_LOG}" ]; then
   if [ "x${ELL_OUTPUT_FILE}" != "x-" ]; then
     export ELL_TMP_SHELL_LOG="${ELL_OUTPUT_FILE}";
   else
-    export ELL_TMP_SHELL_LOG="$(mktemp)";
+    # Declare/assign separately so the assignment does not mask mktemp's status.
+    ELL_TMP_SHELL_LOG="$(mktemp)";
+    export ELL_TMP_SHELL_LOG;
   fi
   export ELL_RECORD=true;
   logging_info "Session being recorded to ${ELL_TMP_SHELL_LOG}";
+  # The command to capture, as separate argv words. For an interactive session
+  # re-exec this ell via its launcher by an absolute path rather than a bare
+  # `ell`: relying on `ell` being on PATH breaks when ell is run in place (e.g.
+  # ./ell.sh) or is not installed.
   if [ "x${ELL_INTERACTIVE}" = "xtrue" ]; then
-    script -q -f -c "ell -i" "${ELL_TMP_SHELL_LOG}";
+    _ell_record_argv=("${BASE_DIR}/ell" -i);
   else
-    script -q -f -c "bash -i" "${ELL_TMP_SHELL_LOG}";
+    _ell_record_argv=(bash -i);
+  fi
+  # GNU/util-linux and BSD/macOS `script` take incompatible command syntax:
+  #   GNU:  script -q -c "CMD-STRING" LOGFILE      (command via $SHELL -c)
+  #   BSD:  script -q LOGFILE CMD [args...]         (command as argv, execvp'd)
+  # BSD script has neither -c nor -f (it errors "illegal option -- f"). Detect
+  # the flavour once (side-effect-free; no PTY, cannot hang) and build the call
+  # accordingly. On GNU, collapse the argv into one %q-quoted string for -c; on
+  # BSD, pass the words positionally after the logfile.
+  if script --version 2>/dev/null | grep -q util-linux; then
+    printf -v _ell_record_cmd '%q ' "${_ell_record_argv[@]}";
+    _ell_record_cmd="${_ell_record_cmd% }";
+    script -q -c "${_ell_record_cmd}" "${ELL_TMP_SHELL_LOG}";
+  else
+    script -q "${ELL_TMP_SHELL_LOG}" "${_ell_record_argv[@]}";
   fi
   logging_debug "Removing ${ELL_TMP_SHELL_LOG}";
-  if [ "z${ELL_OUTPUT_FILE}" = "z-" ]; then
+  if [ "x${ELL_OUTPUT_FILE}" = "x-" ]; then
     rm -f "${ELL_TMP_SHELL_LOG}";
   fi
   unset ELL_TMP_SHELL_LOG;
@@ -125,7 +194,7 @@ if [ "x${ELL_RECORD}" = "xtrue" ] || [ "x${ELL_INTERACTIVE}" = "xtrue" ] && [ "x
   exit 0;
 fi
 
-# Logging_debug "Resolving the template across the search roots";
+# logging_debug "Resolving the template across the search roots";
 ELL_TEMPLATE_FILE="$(resolve_template "${ELL_TEMPLATE}")";
 if [ -z "${ELL_TEMPLATE_FILE}" ]; then
   if [ -n "${ELL_TEMPLATE_PATH}" ]; then
@@ -137,47 +206,70 @@ if [ -z "${ELL_TEMPLATE_FILE}" ]; then
 fi
 logging_debug "Using template: ${ELL_TEMPLATE_FILE}";
 
-# Logging_debug "Checking if we are going to read from a file";
+# logging_debug "Checking if we are going to read from a file";
 if [ -n "${ELL_INPUT_FILE}" ]; then
   if [ "x${ELL_INPUT_FILE}" != "x-" ] && [ ! -f "${ELL_INPUT_FILE}" ]; then
     logging_fatal "Input file not found: ${ELL_INPUT_FILE}";
     exit 1;
   else
     logging_debug "Reading input from file: ${ELL_INPUT_FILE}, overriding USER_PROMPT";
-    USER_PROMPT=$(sed  -e 's/\\/\\\\/g' -e 's/"/\\"/g' "${ELL_INPUT_FILE}" | awk '{printf "%s\\n", $0}');
+    # Read the file as raw text; JSON escaping is handled later by
+    # render_template, and it is run through the post_input hooks below.
+    USER_PROMPT="$(cat "${ELL_INPUT_FILE}")";
   fi
 fi
 
-# Logging_debug "Checking if we are using terminal output as context";
+# logging_debug "Loading the post_input and pre_output hooks";
+# Here-string rather than process substitution: see the note in
+# generate_completion() above (posix + bash 4.1 compatibility).
+mapfile -t post_input_hooks <<< "$(list_plugin_hooks _post_input.sh)";
+logging_debug "Post input hooks: ${post_input_hooks[*]}";
+mapfile -t pre_output_hooks <<< "$(list_plugin_hooks _pre_output.sh)";
+logging_debug "Pre output hooks: ${pre_output_hooks[*]}";
+
+# logging_debug "Checking if we are using terminal output as context";
+# The captured context is kept as raw text (JSON escaping is done later by
+# render_template) and is run through the post_input hooks so that redaction and
+# other input filters apply to the terminal context too, not just USER_PROMPT.
 if [ -z "${ELL_TMP_SHELL_LOG}" ]; then
   logging_debug "ELL_TMP_SHELL_LOG not set";
 else
   logging_debug "Loading shell log from ${ELL_TMP_SHELL_LOG}";
-  SHELL_CONTEXT="$(tail -c 3000 "${ELL_TMP_SHELL_LOG}" | LC_ALL=C awk -f "${BASE_DIR}/helpers/render_to_text.awk" | sed  -e 's/\\/\\\\/g' -e 's/"/\\"/g'| awk '{printf "%s\\n", $0}')";
+  SHELL_CONTEXT="$(tail -c 3000 "${ELL_TMP_SHELL_LOG}" | LC_ALL=C awk -f "${BASE_DIR}/helpers/render_to_text.awk" | piping "${post_input_hooks[@]}")";
 fi
 
-# Logging_debug "Loading the post_input and pre_output hooks";
-mapfile -t post_input_hooks < <(list_plugin_hooks _post_input.sh);
-logging_debug "Post input hooks: ${post_input_hooks[*]}";
-mapfile -t pre_output_hooks < <(list_plugin_hooks _pre_output.sh);
-logging_debug "Pre output hooks: ${pre_output_hooks[*]}";
-
-# Logging_debug "Checking if we are going to enter interactive mode";
+# logging_debug "Checking if we are going to enter interactive mode";
 if [ "x${ELL_INTERACTIVE}" = "xtrue" ]; then
-  logging_info "Interactive mode enabled. ^C to exit";
+  # Debug/info-level hint only (kept quiet at the default log level). The loop
+  # exits cleanly on Ctrl-D (EOF), so name that key rather than Ctrl-C.
+  logging_info "Interactive mode enabled. Press Ctrl-D to exit";
   while true; do
-    echo -ne "${ELL_PS1}";
+    # ELL_PS1 already holds real escape bytes (built with printf when defaulted),
+    # so print it verbatim. Use printf '%s' rather than `echo -ne`, whose -n/-e
+    # handling varies across shells/echo implementations (and matches ELL_PS2).
+    printf '%s' "${ELL_PS1}";
+    # Capture read's status. On EOF (Ctrl-D) read returns non-zero; without
+    # handling it the loop spun forever emitting empty completions. read may
+    # still have stored a final unterminated line together with EOF, so process
+    # that line if it is non-empty, then exit.
     IFS= read -r USER_PROMPT;
+    read_status="${?}";
+    if [ "${read_status}" -ne 0 ] && [ -z "${USER_PROMPT}" ]; then
+      echo;
+      logging_debug "EOF on input, exiting interactive mode";
+      break;
+    fi
     USER_PROMPT="$(echo "${USER_PROMPT}" | piping "${post_input_hooks[@]}")";
     logging_debug "Loading shell log from ${ELL_TMP_SHELL_LOG}";
     if [ -z "${ELL_TMP_SHELL_LOG}" ]; then
       logging_debug "ELL_TMP_SHELL_LOG not set";
     else
-      export SHELL_CONTEXT="$(tail -c 3000 "${ELL_TMP_SHELL_LOG}" | LC_ALL=C awk -f "${BASE_DIR}/helpers/render_to_text.awk" | sed  -e 's/\\/\\\\/g' -e 's/"/\\"/g'| awk '{printf "%s\\n", $0}')";
+      # Raw text through the post_input hooks (redaction etc.); render_template
+      # handles JSON escaping. Declare/assign separately (SC2155).
+      SHELL_CONTEXT="$(tail -c 3000 "${ELL_TMP_SHELL_LOG}" | LC_ALL=C awk -f "${BASE_DIR}/helpers/render_to_text.awk" | piping "${post_input_hooks[@]}")";
+      export SHELL_CONTEXT;
     fi
-    PAYLOAD="$(eval "cat <<EOF
-$(cat "${ELL_TEMPLATE_FILE}")
-EOF")";
+    PAYLOAD="$(render_template "${ELL_TEMPLATE_FILE}")";
     if [ -z "${PAYLOAD}" ]; then
       logging_error "Failed to build request payload from template ${ELL_TEMPLATE_FILE}";
       continue;
@@ -193,9 +285,7 @@ EOF")";
 else
   USER_PROMPT=$(echo "${USER_PROMPT}" | piping "${post_input_hooks[@]}");
 
-  PAYLOAD="$(eval "cat <<EOF
-$(cat "${ELL_TEMPLATE_FILE}")
-EOF")";
+  PAYLOAD="$(render_template "${ELL_TEMPLATE_FILE}")";
   if [ -z "${PAYLOAD}" ]; then
     logging_fatal "Failed to build request payload from template ${ELL_TEMPLATE_FILE}";
     exit 1;
diff --git a/helpers/backend_common.sh b/helpers/backend_common.sh
new file mode 100644
index 0000000..0cf19c6
--- /dev/null
+++ b/helpers/backend_common.sh
@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+
+# Shared logic for the LLM backends.
+#
+# The openai and gemini backends differ only in their streaming parsers (SSE
+# line framing vs a single pretty-printed JSON array) and in a handful of
+# provider-specific JSON paths / sentinels. Everything else -- the non-streaming
+# request/parse path, the end-of-stream success/failure reporting, and the
+# PIPESTATUS epilogue -- was duplicated almost line-for-line. These helpers hold
+# that shared logic, parameterised by the provider-specific bits, so a fix to
+# any of it happens in one place.
+#
+# ell_curl / json_* / logging_* are provided by ell.sh (sourced before the
+# backends), same as for the backends themselves.
+
+# ell_backend_nonstreaming <url> <content_path> <finish_path> <stop_value> \
+#                          <usage_key> <usage_prompt> <usage_completion> <usage_total>
+# Run the non-streaming request: POST stdin to <url>, parse the response, and on
+# a normal finish print the completion text (from <content_path>) followed by a
+# blank line, logging usage if present. Prints nothing and returns non-zero on
+# transport failure, parse failure, or an abnormal finish reason.
+#
+#   content_path   json path of the completion text (e.g. choices.0.message.content)
+#   finish_path    json path of the finish reason  (e.g. choices.0.finish_reason)
+#   stop_value     the finish reason meaning "ok"  (e.g. stop / STOP)
+#   usage_key      json path that exists when usage is present (e.g. usage)
+#   usage_*        json paths of the three usage counters
+ell_backend_nonstreaming() {
+  local url="${1}" content_path="${2}" finish_path="${3}" stop_value="${4}";
+  local usage_key="${5}" usage_prompt="${6}" usage_completion="${7}" usage_total="${8}";
+  local response curl_status prompt_tokens completion_tokens total_tokens;
+
+  logging_debug "Streaming disabled";
+  response=$(ell_curl "${url}" \
+    --header "Content-Type: application/json" \
+    --data-binary @-);
+  curl_status="${?}";
+
+  if [ "${curl_status}" -ne 0 ]; then
+    logging_fatal "Failed to generate completion: $(ell_curl_strerror "${curl_status}") (curl exit ${curl_status})";
+    logging_debug "Response: ${response}";
+    # Propagate curl's real exit code (as-is), matching the streaming path
+    # (ell_backend_check_pipestatus) and the contract in docs/Backends.md, so a
+    # transport failure stays diagnosable instead of collapsing to a bare 1.
+    return "${curl_status}";
+  fi
+
+  if ! json_parse "${response}"; then
+    logging_error "Unexpected format: ${response}";
+    return 1;
+  fi
+
+  if ! json_has "${finish_path}"; then
+    logging_error "Unexpected format: ${response}";
+    return 1;
+  fi
+
+  if [ "x$(json_get "${finish_path}")" != "x${stop_value}" ]; then
+    logging_error "Unexpected finish reason: $(json_get "${finish_path}")";
+    return 1;
+  fi
+
+  json_get "${content_path}";
+  echo "";
+  if json_has "${usage_key}"; then
+    prompt_tokens=$(json_get "${usage_prompt}");
+    completion_tokens=$(json_get "${usage_completion}");
+    total_tokens=$(json_get "${usage_total}");
+    echo '';
+    logging_info "usage: prompt_tokens=${prompt_tokens}, completion_tokens=${completion_tokens}, total_tokens=${total_tokens}";
+  fi
+}
+
+# ell_backend_report_stream_end <emitted> <received> <unparsable> <bad_stop> <url>
+# Emit the shared end-of-stream diagnostics and exit with the right code. Called
+# from INSIDE the streaming reader subshell, so it uses `exit`, not `return`:
+#   exit 3 - nothing usable was produced (empty / unparsable / no content)
+#   exit 4 - a non-stop finish reason (truncated / filtered) was seen
+# Returns 0 (does not exit) when content was emitted and the finish was normal.
+ell_backend_report_stream_end() {
+  local emitted="${1}" received="${2}" unparsable="${3}" bad_stop="${4}" url="${5}";
+  if [ "${emitted}" -eq 0 ]; then
+    if [ "${received}" -eq 0 ]; then
+      logging_error "No data received from ${url} (empty or non-streaming response)";
+    elif [ "${unparsable}" -ne 0 ]; then
+      logging_error "Response could not be parsed as a valid streaming completion";
+    else
+      logging_error "Streaming response contained no content";
+    fi
+    exit 3;
+  fi
+  if [ "${bad_stop}" -ne 0 ]; then
+    exit 4;
+  fi
+}
+
+# ell_backend_check_pipestatus <curl_status> <stream_status>
+# Shared PIPESTATUS epilogue for the streaming path. The caller must capture
+# PIPESTATUS immediately after the `curl | { reader }` pipeline (any command
+# resets it) and pass the two stages in. Preserves the distinct exit codes so a
+# curl/transport failure is distinguishable from a stream-parse failure.
+ell_backend_check_pipestatus() {
+  local curl_status="${1}" stream_status="${2}";
+  if [ "${curl_status}" -ne 0 ]; then
+    logging_fatal "Failed to generate completion: $(ell_curl_strerror "${curl_status}") (curl exit ${curl_status})";
+    return "${curl_status}";
+  fi
+  if [ "${stream_status}" -ne 0 ]; then
+    return "${stream_status}";
+  fi
+  return 0;
+}
+
+export -f ell_backend_nonstreaming;
+export -f ell_backend_report_stream_end;
+export -f ell_backend_check_pipestatus;
diff --git a/helpers/http.sh b/helpers/http.sh
new file mode 100644
index 0000000..1b80047
--- /dev/null
+++ b/helpers/http.sh
@@ -0,0 +1,225 @@
+#!/usr/bin/env bash
+
+# Shared HTTP helper for the LLM backends.
+#
+# Centralises curl invocation so every backend gets the same robustness
+# treatment instead of hand-rolling `curl --silent ...` four times:
+#
+#   * connection/overall timeouts, so a stalled server does not hang ell
+#     forever (previously there was no timeout at all);
+#   * HTTP error handling, so a 401/429/500 becomes a non-zero curl exit
+#     (previously curl returned 0 with an error body and the failure only
+#     surfaced later as a vague "Unexpected format").
+#
+# Configuration (all optional, read from the environment):
+#   ELL_CONNECT_TIMEOUT  seconds to wait for the TCP/TLS connection (default 10)
+#   ELL_MAX_TIME         seconds for the whole transfer; 0 = no limit
+#                        (default 0, so long streaming completions are not
+#                        killed mid-response)
+#   ELL_CURL_EXTRA_OPTS  extra curl options, word-split, for advanced users
+#   ELL_CURL_AUTH_HEADER a single HTTP header (e.g. "Authorization: Bearer X")
+#                        that must NOT appear on curl's command line. It is fed
+#                        to curl through a --config file so the secret is not
+#                        visible in `ps` / /proc/<pid>/cmdline.
+#   ELL_ALLOW_INSECURE_URL  set to "true" to permit sending an auth header over
+#                        a plaintext http:// URL (otherwise refused, to avoid
+#                        leaking the credential in cleartext). Loopback hosts
+#                        (localhost/127.0.0.1/::1) are always allowed.
+
+# Detect whether this curl supports --fail-with-body (curl >= 7.76). It makes
+# curl exit non-zero on HTTP >= 400 while still printing the response body, so
+# error details (rate-limit messages etc.) remain visible. Older curl falls back
+# to --fail, which also exits non-zero but discards the body.
+#
+# The result is cached so it is probed at most once per process even though the
+# value is computed lazily (so tests can stub curl before the first probe).
+_ell_curl_fail_opt() {
+  if [ -z "${_ELL_CURL_FAIL_OPT:-}" ]; then
+    if curl --help all 2>/dev/null | grep -q -- '--fail-with-body'; then
+      _ELL_CURL_FAIL_OPT="--fail-with-body";
+    else
+      _ELL_CURL_FAIL_OPT="--fail";
+    fi
+  fi
+  printf '%s' "${_ELL_CURL_FAIL_OPT}";
+}
+
+# _ell_on_windows: return 0 when running under a Windows bash (Git Bash / MSYS2
+# / Cygwin), where filesystem paths are POSIX-style (e.g. /c/Users/...) but the
+# native curl expects Windows paths (C:/Users/...). Detected from $OSTYPE, which
+# is "msys" for Git Bash, "cygwin" for Cygwin, and "win32" in rare setups.
+_ell_on_windows() {
+  case "${OSTYPE:-}" in
+    msys|cygwin|win32) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# _ell_fixup_file_url <url>: on Windows bash, rewrite a file:// URL whose path is
+# a POSIX/MSYS path (/c/Users/... or /tmp/...) into the file:///C:/... form the
+# native curl understands, using cygpath. On every other platform, and for any
+# non-file:// URL, the input is printed back unchanged. Any optional "#fragment"
+# ell appends to force curl's URL parsing is preserved.
+_ell_fixup_file_url() {
+  local url="${1}" path frag win;
+  # Only file:// URLs on Windows bash need fixing; everything else is verbatim.
+  if ! _ell_on_windows || ! command -v cygpath >/dev/null 2>&1; then
+    printf '%s' "${url}";
+    return 0;
+  fi
+  case "${url}" in
+    file://*|FILE://*) ;;
+    *) printf '%s' "${url}"; return 0 ;;
+  esac
+  # Strip the scheme (and an authority-less "//") to get the raw path, then split
+  # off any trailing "#fragment" so it is not passed through cygpath.
+  path="${url#*://}";
+  path="${path#/}";              # tolerate file:///path (leading extra slash)
+  case "${path}" in
+    *#*) frag="#${path#*#}"; path="${path%%#*}" ;;
+    *)   frag="" ;;
+  esac
+  path="/${path}";              # restore a leading slash for cygpath
+  # cygpath -m yields a Windows path with forward slashes (C:/Users/...), which
+  # is exactly what a file:// URL wants. If conversion fails, fall back to the
+  # original URL rather than emitting something broken.
+  win="$(cygpath -m -- "${path}" 2>/dev/null)" || { printf '%s' "${url}"; return 0; };
+  if [ -z "${win}" ]; then printf '%s' "${url}"; return 0; fi
+  printf 'file:///%s%s' "${win}" "${frag}";
+}
+
+# _ell_url_is_secure <url>: return 0 if it is safe to send a credential to
+# <url>. https:// and file:// are safe; http:// is only safe for loopback hosts
+# (localhost / 127.0.0.1 / ::1). Any other scheme is treated as safe so this
+# check only ever blocks the clear risk: an explicit plaintext http:// remote.
+_ell_url_is_secure() {
+  local url="${1}" host rest;
+  case "${url}" in
+    https://*|HTTPS://*) return 0 ;;
+    file://*|FILE://*)   return 0 ;;
+    http://*|HTTP://*)
+      # Strip scheme, then take the authority (up to the first '/' or '?').
+      rest="${url#*://}";
+      host="${rest%%[/?]*}";
+      # Split off the port. A bracketed IPv6 authority (e.g. "[::1]:8080")
+      # contains ':' inside the brackets, so it needs a two-step trim that keeps
+      # the brackets: take what is inside "[...]" and rebuild "[inner]", which
+      # drops any trailing ":port". A non-bracketed host just strips at the
+      # first ':'.
+      case "${host}" in
+        '['*']'*)
+          host="${host#\[}";      # drop leading '['
+          host="${host%%]*}";     # keep up to (not including) the first ']'
+          host="[${host}]";       # rebuild the bracketed address, sans :port
+          ;;
+        *) host="${host%%:*}" ;;
+      esac
+      case "${host}" in
+        localhost|127.0.0.1|'[::1]'|::1) return 0 ;;
+        *) return 1 ;;
+      esac
+      ;;
+    *) return 0 ;;
+  esac
+}
+
+# ell_curl <url> [extra curl args...]
+# Invoke curl with ell's shared options plus any per-call arguments (headers,
+# --data-binary, etc.). Reads the request body from stdin when the caller
+# passes --data-binary @-. Returns curl's exit status.
+#
+# If ELL_CURL_AUTH_HEADER is set, that header is passed to curl via a --config
+# file (not on the command line), so the credential is not exposed in the
+# process table. A temporary config file with 0600 permissions is used and
+# removed immediately; it holds only the header line.
+ell_curl() {
+  local url="${1}";
+  shift;
+  # On Windows bash a file:// URL carries a POSIX path the native curl cannot
+  # read; rewrite it to file:///C:/... there. A no-op everywhere else.
+  url="$(_ell_fixup_file_url "${url}")";
+  # Populate the fail-option cache in this (non-subshell) scope so it is probed
+  # at most once per process, then read the cached value.
+  _ell_curl_fail_opt >/dev/null;
+  local -a opts;
+  opts=(
+    --silent
+    --show-error
+    "${_ELL_CURL_FAIL_OPT}"
+    --connect-timeout "${ELL_CONNECT_TIMEOUT:-10}"
+    --max-time "${ELL_MAX_TIME:-0}"
+  );
+  # Allow advanced users to append arbitrary curl options.
+  if [ -n "${ELL_CURL_EXTRA_OPTS}" ]; then
+    # Intentional word splitting so ELL_CURL_EXTRA_OPTS can hold several opts.
+    # shellcheck disable=SC2206
+    opts+=(${ELL_CURL_EXTRA_OPTS});
+  fi
+
+  # Refuse to send credentials over a plaintext http:// URL (the key would go
+  # out in cleartext). https://, file:// and loopback http hosts are fine, and
+  # ELL_ALLOW_INSECURE_URL=true is an explicit opt-out.
+  if [ -n "${ELL_CURL_AUTH_HEADER}" ] && ! _ell_url_is_secure "${url}"; then
+    if [ "x${ELL_ALLOW_INSECURE_URL}" != "xtrue" ]; then
+      logging_fatal "Refusing to send credentials to a non-HTTPS URL: ${url}";
+      logging_fatal "Use https://, or set ELL_ALLOW_INSECURE_URL=true to override.";
+      return 1;
+    fi
+    logging_warn "Sending credentials over an insecure URL (ELL_ALLOW_INSECURE_URL=true): ${url}";
+  fi
+
+  local auth_cfg="" status _ell_auth_val;
+  if [ -n "${ELL_CURL_AUTH_HEADER}" ]; then
+    auth_cfg="$(mktemp)" || {
+      logging_error "Failed to create temp file for auth header";
+      return 1;
+    };
+    # chmod 600 before writing so the secret is never briefly world-readable.
+    chmod 600 "${auth_cfg}";
+    # curl config syntax: header = "NAME: value". Inside double quotes curl
+    # treats backslash as an escape introducer (\\, \", \t, \n, \r, \v), so a
+    # header value must have its backslashes escaped BEFORE its double quotes
+    # (escaping quotes first would then double-escape the added backslashes).
+    _ell_auth_val="${ELL_CURL_AUTH_HEADER//\\/\\\\}";   # \ -> \\
+    _ell_auth_val="${_ell_auth_val//\"/\\\"}";          # " -> \"
+    printf 'header = "%s"\n' "${_ell_auth_val}" > "${auth_cfg}";
+    opts+=(--config "${auth_cfg}");
+  fi
+
+  curl "${url}" "${opts[@]}" "${@}";
+  status="${?}";
+  # Remove the temp credential file after capturing curl's status. Cleanup is
+  # explicit (rather than a RETURN trap) because there are no early returns
+  # between creating auth_cfg and here, and doing it inline keeps the captured
+  # exit status unambiguous regardless of shell trap semantics.
+  if [ -n "${auth_cfg}" ]; then
+    rm -f "${auth_cfg}";
+  fi
+  return "${status}";
+}
+
+# ell_curl_strerror <exit-code>: print a human-readable, actionable explanation
+# for a curl exit code. Falls back to a generic message for codes not listed.
+# See `man curl` (EXIT CODES) for the full list; only the ones users actually
+# hit are spelled out here.
+ell_curl_strerror() {
+  case "${1}" in
+    6)  printf 'could not resolve host (check ELL_API_URL and your network/DNS)' ;;
+    7)  printf 'failed to connect (server down or wrong host/port in ELL_API_URL?)' ;;
+    22) printf 'server returned an HTTP error (>= 400); check ELL_API_KEY, the model, and ELL_API_URL' ;;
+    28) printf 'request timed out (raise ELL_MAX_TIME / ELL_CONNECT_TIMEOUT, or check the network)' ;;
+    35) printf 'TLS handshake failed (check the endpoint supports HTTPS)' ;;
+    52) printf 'empty reply from server' ;;
+    56) printf 'network error while receiving data' ;;
+    60) printf 'TLS certificate problem (untrusted or invalid certificate)' ;;
+    3)  printf 'malformed URL (is ELL_API_URL set correctly?)' ;;
+    *)  printf 'curl error' ;;
+  esac
+}
+
+export -f _ell_curl_fail_opt;
+export -f _ell_on_windows;
+export -f _ell_fixup_file_url;
+export -f _ell_url_is_secure;
+export -f ell_curl;
+export -f ell_curl_strerror;
diff --git a/helpers/http.test.sh b/helpers/http.test.sh
new file mode 100644
index 0000000..e1eb20a
--- /dev/null
+++ b/helpers/http.test.sh
@@ -0,0 +1,262 @@
+#!/usr/bin/env bash
+
+# Self-checking tests for llm_backends/http.sh (ell_curl).
+#
+# ell_curl centralises curl invocation so every backend gets timeouts and HTTP
+# error handling. Rather than depend on a live server (the CI images are minimal
+# and may lack python/nc), we stub `curl` with a shell function that records the
+# arguments it was given, and assert that ell_curl passes the robustness options
+# through. One real call against an unreachable address checks that a connect
+# timeout actually bounds the wait.
+
+set -o posix;
+
+DIR="$(dirname "${0}")";
+. "${DIR}/../tests/assert.sh";
+
+ELL_LOG_LEVEL=0;
+export ELL_LOG_LEVEL;
+. "${DIR}/logging.sh";
+. "${DIR}/http.sh";
+
+echo "http / ell_curl tests";
+echo "=====================";
+
+# The temp auth-config file is chmod 600 so the credential is owner-only. On
+# platforms where POSIX permission bits are not trustworthy (Windows Git Bash /
+# MSYS over NTFS), chmod is effectively a no-op and stat cannot confirm 0600, so
+# that specific assertion is SKIPped (see docs/Configuration.md, "Windows").
+# Probe by setting a distinctive mode (world-writable) and checking it sticks:
+# if chmod cannot actually change the group/other bits, POSIX perms are not
+# trustworthy here and the 0600 assertion below is not meaningful.
+perms_trustworthy() {
+  local probe p;
+  probe="$(mktemp 2>/dev/null)" || return 1;
+  chmod 666 "${probe}" 2>/dev/null || { rm -f "${probe}"; return 1; }
+  p="$(stat -c '%a' "${probe}" 2>/dev/null || stat -f '%Lp' "${probe}" 2>/dev/null)";
+  rm -f "${probe}";
+  case "${p}" in *[2367][2367]) return 0 ;; *) return 1 ;; esac
+}
+if perms_trustworthy; then PERMS_OK=true; else PERMS_OK=false; fi
+
+# Stub curl: print every argument on its own line so we can inspect them.
+ARGS_FILE="$(mktemp)";
+trap 'rm -f "${ARGS_FILE}"' EXIT;
+curl() {
+  printf '%s\n' "${@}" > "${ARGS_FILE}";
+  return 0;
+}
+
+# has_arg <value>: true if the stubbed curl received <value> as an argument.
+has_arg() {
+  grep -qxF -- "${1}" "${ARGS_FILE}";
+}
+
+# --- Option injection -------------------------------------------------------
+
+# Resolve the fail option BEFORE the main call. _ell_curl_fail_opt probes with
+# `curl --help`, which the stub also records; resolving it first (and letting it
+# cache) keeps that probe from overwriting ARGS_FILE during the assertions.
+# With curl stubbed, `--help` yields no match so the value is --fail here.
+fail_opt="$(_ell_curl_fail_opt)";
+
+ELL_CONNECT_TIMEOUT=7 ELL_MAX_TIME=0 \
+  ell_curl "https://example.com" --header "X: 1" --data-binary @- </dev/null;
+
+assert_success "url passed through"          has_arg "https://example.com";
+assert_success "silent enabled"              has_arg "--silent";
+assert_success "connect-timeout flag set"    has_arg "--connect-timeout";
+assert_success "connect-timeout value used"  has_arg "7";
+assert_success "max-time flag set"           has_arg "--max-time";
+assert_success "caller header preserved"     has_arg "X: 1";
+assert_success "caller data-binary preserved" has_arg "--data-binary";
+
+# The fail option (either --fail-with-body on newer curl or --fail on older,
+# here --fail because the stub's --help matches neither) is injected.
+assert_success "fail option present" has_arg "${fail_opt}";
+case "${fail_opt}" in
+  --fail|--fail-with-body) _assert_pass "fail option is a known value";;
+  *) _assert_fail "fail option is a known value"; echo "  got: ${fail_opt}";;
+esac
+
+# Default connect timeout is applied when the variable is unset.
+unset ELL_CONNECT_TIMEOUT;
+ell_curl "https://example.com" </dev/null;
+assert_success "default connect-timeout (10) applied" has_arg "10";
+
+# Extra options are appended when requested.
+ELL_CURL_EXTRA_OPTS="--proto =https" ell_curl "https://example.com" </dev/null;
+assert_success "extra opt --proto passed"  has_arg "--proto";
+assert_success "extra opt value passed"    has_arg "=https";
+unset ELL_CURL_EXTRA_OPTS;
+
+# --- Auth header is not exposed on the command line -------------------------
+# ELL_CURL_AUTH_HEADER must be passed via a --config file, never as an argv
+# element, so the secret is not visible in ps / /proc/<pid>/cmdline. Use a stub
+# that records argv and captures the --config file's contents.
+CFG_FILE="$(mktemp)";
+PERM_FILE="$(mktemp)";
+trap 'rm -f "${ARGS_FILE}" "${CFG_FILE}" "${PERM_FILE}"' EXIT;
+curl() {
+  printf '%s\n' "${@}" > "${ARGS_FILE}";
+  local prev="";
+  for a in "${@}"; do
+    if [ "${prev}" = "--config" ]; then
+      cp "${a}" "${CFG_FILE}" 2>/dev/null;
+      # Capture the permission bits while the file still exists (ell_curl removes
+      # it after this call). GNU stat then BSD/macOS stat.
+      { stat -c '%a' "${a}" 2>/dev/null || stat -f '%Lp' "${a}" 2>/dev/null; } > "${PERM_FILE}";
+    fi
+    prev="${a}";
+  done
+  return 0;
+}
+
+secret="Authorization: Bearer sk-DO-NOT-LEAK-123";
+ELL_CURL_AUTH_HEADER="${secret}" ell_curl "https://example.com" --data-binary @- </dev/null;
+
+# The secret must NOT appear anywhere in the argv the stub received.
+if grep -qF -- "sk-DO-NOT-LEAK-123" "${ARGS_FILE}"; then
+  _assert_fail "auth header value is not on the command line";
+else
+  _assert_pass "auth header value is not on the command line";
+fi
+# --config must be present, and the config file must carry the header.
+assert_success "auth header passed via --config" has_arg "--config";
+if grep -qF -- "sk-DO-NOT-LEAK-123" "${CFG_FILE}"; then
+  _assert_pass "auth header delivered through the config file";
+else
+  _assert_fail "auth header delivered through the config file";
+fi
+# The temp config file must be mode 0600 (only the owner can read the secret).
+# The last two octal digits (group, other) must be 0; strip any leading digit.
+cfg_perms="$(cat "${PERM_FILE}" 2>/dev/null)";
+if [ "${PERMS_OK}" = "true" ]; then
+  case "${cfg_perms}" in
+    600|0600) _assert_pass "temp auth config is mode 0600" ;;
+    *) _assert_fail "temp auth config is mode 0600"; echo "  perms: ${cfg_perms}" ;;
+  esac
+else
+  echo "SKIP: temp auth config is mode 0600 (POSIX perms not trustworthy here)";
+fi
+# The temp config file curl was pointed at must be removed after the call.
+cfg_path="$(awk '/^--config$/{getline; print; exit}' "${ARGS_FILE}")";
+if [ -n "${cfg_path}" ] && [ -e "${cfg_path}" ]; then
+  _assert_fail "temp auth config is cleaned up";
+  echo "  still present: ${cfg_path}";
+else
+  _assert_pass "temp auth config is cleaned up";
+fi
+# A header value containing backslashes and double quotes must be escaped for
+# curl's config-file syntax: inside double quotes curl treats "\" as an escape
+# introducer, so both "\" -> "\\" and '"' -> '\"'. Otherwise a value like
+# 'a\tb' would be read back as 'a<TAB>b' and the credential mangled. The stub
+# above captures the written config into CFG_FILE.
+ELL_CURL_AUTH_HEADER='X-Auth: a\tb"c\' \
+  ell_curl "https://example.com" --data-binary @- </dev/null;
+# The config must contain the doubled backslashes and the escaped quote, not the
+# raw single backslashes.
+if grep -qF -- 'header = "X-Auth: a\\tb\"c\\"' "${CFG_FILE}"; then
+  _assert_pass "auth header backslashes and quotes are escaped for curl config";
+else
+  _assert_fail "auth header backslashes and quotes are escaped for curl config";
+  echo "  config: $(cat "${CFG_FILE}" 2>/dev/null)";
+fi
+unset ELL_CURL_AUTH_HEADER;
+
+# curl's exit status must propagate unchanged through the auth-header path,
+# where ell_curl also cleans up the temp --config file after the call. This
+# guards against the cleanup step (or any trap semantics) clobbering the status.
+curl() {
+  # Still write the config so cleanup has a real file to remove, then fail.
+  local prev="";
+  for a in "${@}"; do
+    if [ "${prev}" = "--config" ]; then cp "${a}" "${CFG_FILE}" 2>/dev/null; fi
+    prev="${a}";
+  done
+  return 22;
+}
+ELL_CURL_AUTH_HEADER="Authorization: Bearer sk-STATUS" \
+  ell_curl "https://example.com" --data-binary @- </dev/null >/dev/null 2>&1;
+auth_status="${?}";
+assert_equals "curl status propagates through auth path" "22" "${auth_status}";
+
+unset ELL_CURL_AUTH_HEADER;
+# Restore the recording stub for subsequent assertions.
+curl() {
+  printf '%s\n' "${@}" > "${ARGS_FILE}";
+  return 0;
+}
+
+# --- Refuse credentials over a plaintext remote URL -------------------------
+# _ell_url_is_secure classifies where it is safe to send a credential.
+assert_success "https is secure"           _ell_url_is_secure "https://api.openai.com/v1";
+assert_success "file is secure"            _ell_url_is_secure "file:///tmp/x.json";
+assert_success "http loopback is secure"   _ell_url_is_secure "http://localhost:8080/v1";
+assert_success "http 127.0.0.1 is secure"  _ell_url_is_secure "http://127.0.0.1/v1";
+# Bracketed IPv6 loopback, with and without a port, must be recognised as
+# loopback. The ':' inside "[::1]" must not truncate the host to "[".
+assert_success "http [::1] is secure"       _ell_url_is_secure "http://[::1]/v1";
+assert_success "http [::1]:port is secure"  _ell_url_is_secure "http://[::1]:8080/v1";
+assert_failure "http remote is insecure"   _ell_url_is_secure "http://api.example.com/v1";
+# A non-loopback bracketed IPv6 host is still insecure over plaintext http.
+assert_failure "http remote IPv6 is insecure" _ell_url_is_secure "http://[2001:db8::1]:8080/v1";
+
+# With an auth header and a plaintext remote URL, ell_curl must refuse and NOT
+# invoke curl (so the key is never sent in cleartext).
+insecure_ran=0;
+curl() { insecure_ran=1; return 0; }
+ELL_CURL_AUTH_HEADER="Authorization: Bearer sk-INSECURE" \
+  ell_curl "http://api.example.com/v1" --data-binary @- </dev/null >/dev/null 2>&1;
+insecure_status="${?}";
+assert_not_equals "refuses credential over remote http" "0" "${insecure_status}";
+assert_equals     "curl not invoked when refused" "0" "${insecure_ran}";
+
+# The explicit opt-out allows it.
+optout_ran=0;
+curl() { optout_ran=1; return 0; }
+ELL_ALLOW_INSECURE_URL=true ELL_CURL_AUTH_HEADER="Authorization: Bearer sk-INSECURE" \
+  ell_curl "http://api.example.com/v1" --data-binary @- </dev/null >/dev/null 2>&1;
+assert_equals "opt-out allows insecure send" "1" "${optout_ran}";
+unset ELL_ALLOW_INSECURE_URL ELL_CURL_AUTH_HEADER;
+
+# Without a credential, a plaintext remote URL is allowed (nothing to leak).
+noauth_ran=0;
+curl() { noauth_ran=1; return 0; }
+ell_curl "http://api.example.com/v1" --data-binary @- </dev/null >/dev/null 2>&1;
+assert_equals "no-auth plaintext URL is allowed" "1" "${noauth_ran}";
+
+# Restore the recording stub for any later assertions.
+curl() {
+  printf '%s\n' "${@}" > "${ARGS_FILE}";
+  return 0;
+}
+
+# --- Real timeout against an unreachable address ----------------------------
+# Drop the stub so the real curl runs.
+unset -f curl;
+if command -v curl >/dev/null 2>&1; then
+  # 10.255.255.1 is a TEST-NET / non-routable address; the connect must time out
+  # quickly rather than hang. Assert curl exits non-zero within the bound.
+  ELL_CONNECT_TIMEOUT=2 ELL_MAX_TIME=3 \
+    ell_curl "http://10.255.255.1:9/" --data-binary @- </dev/null >/dev/null 2>&1;
+  status="${?}";
+  if [ "${status}" -ne 0 ]; then
+    _assert_pass "unreachable host fails (does not hang)";
+  else
+    _assert_fail "unreachable host fails (does not hang)";
+  fi
+else
+  echo "SKIP: real timeout check (curl not installed)";
+fi
+
+# --- ell_curl_strerror translates curl exit codes ---------------------------
+# Common curl exit codes must map to a readable, actionable message rather than
+# a bare number; unknown codes fall back to a generic message.
+assert_contains "code 6 mentions host resolution"  "$(ell_curl_strerror 6)"  "resolve host";
+assert_contains "code 7 mentions connect failure"  "$(ell_curl_strerror 7)"  "connect";
+assert_contains "code 28 mentions timeout"         "$(ell_curl_strerror 28)" "timed out";
+assert_contains "code 60 mentions certificate"     "$(ell_curl_strerror 60)" "certificate";
+assert_equals   "unknown code falls back"          "curl error" "$(ell_curl_strerror 250)";
+
+assert_summary;
diff --git a/helpers/json.sh b/helpers/json.sh
index 6bfb9f7..9a3fa18 100644
--- a/helpers/json.sh
+++ b/helpers/json.sh
@@ -58,10 +58,23 @@ _json_skip_ws() {
 # leave the fully decoded value in _JSON_STR. Advances the cursor past the
 # closing quote.
 _json_parse_string() {
-  local out="" c hex code
+  local out="" c hex code rest chunk
   # Skip the opening quote.
   _JSON_I=$((_JSON_I + 1));
   while [ "${_JSON_I}" -lt "${_JSON_N}" ]; do
+    # Fast path: copy the whole run of ordinary characters up to the next '"'
+    # or '\' in one operation instead of appending one character per loop
+    # iteration (which is O(n^2) for long string values). ${rest%%[\"\\]*}
+    # yields everything before the first quote or backslash.
+    rest="${_JSON_S:${_JSON_I}}";
+    chunk="${rest%%[\"\\]*}";
+    if [ -n "${chunk}" ]; then
+      out="${out}${chunk}";
+      _JSON_I=$((_JSON_I + ${#chunk}));
+      if [ "${_JSON_I}" -ge "${_JSON_N}" ]; then
+        break;
+      fi
+    fi
     c="${_JSON_S:${_JSON_I}:1}";
     if [ "${c}" = '"' ]; then
       _JSON_I=$((_JSON_I + 1));
@@ -203,12 +216,15 @@ _json_parse_number() {
 # arrays cannot use an empty subscript, so the empty path maps to this key.
 _JSON_ROOT=$'\001root';
 
-# _json_key: translate a logical path ("" for root) into a storage key.
+# _json_key: translate a logical path ("" for root) into a storage key, leaving
+# the result in _JSON_KEY. This deliberately avoids command substitution
+# ($(_json_key ...)) which forked a subshell on every value/lookup and was a
+# dominant cost when parsing many small objects.
 _json_key() {
   if [ -z "${1}" ]; then
-    printf '%s' "${_JSON_ROOT}";
+    _JSON_KEY="${_JSON_ROOT}";
   else
-    printf '%s' "${1}";
+    _JSON_KEY="${1}";
   fi
 }
 
@@ -216,7 +232,7 @@ _json_key() {
 _json_parse_value() {
   local path key c;
   path="${1}";
-  key="$(_json_key "${path}")";
+  _json_key "${path}"; key="${_JSON_KEY}";
   _json_skip_ws;
   if [ "${_JSON_I}" -ge "${_JSON_N}" ]; then
     _json_error "unexpected end of input";
@@ -342,7 +358,7 @@ json_parse() {
 # json_get: print the value at <path>, or return non-zero if missing.
 json_get() {
   local key;
-  key="$(_json_key "${1}")";
+  _json_key "${1}"; key="${_JSON_KEY}";
   if [ -z "${JSON_TYPE[${key}]+x}" ]; then
     return 1;
   fi
@@ -353,7 +369,7 @@ json_get() {
 # json_has: succeed if <path> exists and is not null.
 json_has() {
   local key;
-  key="$(_json_key "${1}")";
+  _json_key "${1}"; key="${_JSON_KEY}";
   if [ -z "${JSON_TYPE[${key}]+x}" ]; then
     return 1;
   fi
diff --git a/helpers/json.test.sh b/helpers/json.test.sh
index 3325661..d9c9d92 100644
--- a/helpers/json.test.sh
+++ b/helpers/json.test.sh
@@ -77,4 +77,24 @@ assert_failure "rejects incomplete exp"   json_is_valid '1e';
 assert_failure "rejects unterminated str" json_is_valid '{"a":"oops}';
 assert_failure "rejects empty input"      json_is_valid '';
 
+# --- Long / mixed string values (exercise the bulk-copy fast path) ----------
+# The string parser copies runs of ordinary characters in one operation rather
+# than one character at a time. These cases guard that the fast path preserves
+# long values and still interleaves escapes / unicode correctly.
+
+# A long run of ordinary characters round-trips intact.
+long="$(printf 'a%.0s' $(seq 1 2000))";
+assert_success "parses a long plain string" json_parse "{\"s\":\"${long}\"}";
+assert_equals  "long plain string preserved" "${long}" "$(json_get s)";
+
+# Ordinary runs interleaved with escapes and a surrogate-pair emoji.
+assert_success "parses mixed string" \
+  json_parse '{"t":"hi \"q\" \u0041 \n x \ud83d\ude00 end"}';
+assert_equals  "mixed string decoded correctly" \
+  "$(printf 'hi "q" A \n x \360\237\230\200 end')" "$(json_get t)";
+
+# A string that begins immediately with an escape (empty leading ordinary run).
+assert_success "parses leading-escape string" json_parse '{"t":"\n after"}';
+assert_equals  "leading-escape decoded" "$(printf '\n after')" "$(json_get t)";
+
 assert_summary;
diff --git a/helpers/load_config.sh b/helpers/load_config.sh
index 007b895..7498d88 100644
--- a/helpers/load_config.sh
+++ b/helpers/load_config.sh
@@ -9,6 +9,64 @@
 #   3. $PWD/.ellrc                                    (per-project config)
 #   4. $ELL_CONFIG                                    (explicit override)
 
+# _config_is_trusted <file>
+# Config files are sourced, i.e. executed as shell code. Only source a file
+# that cannot have been planted or tampered with by another user: it must be
+# owned by the current user (or root) and must not be writable by its group or
+# by others. This closes the "run ell in a directory containing a hostile
+# .ellrc" arbitrary-code-execution hole (the $PWD/.ellrc case in particular).
+#
+# If ownership/permissions cannot be determined (no usable stat), err on the
+# side of caution and refuse to source the file.
+_config_is_trusted() {
+  local file="${1}" owner perms;
+
+  # Owner UID and octal permission bits, trying GNU stat then BSD/macOS stat.
+  owner="$(stat -c '%u' "${file}" 2>/dev/null || stat -f '%u' "${file}" 2>/dev/null)";
+  perms="$(stat -c '%a' "${file}" 2>/dev/null || stat -f '%Lp' "${file}" 2>/dev/null)";
+
+  # These refusals mean a config file the user created is being ignored, which
+  # otherwise looks like "my settings don't work" with no explanation. Report
+  # them at error level so they are visible at the default log level (a missing
+  # config, by contrast, is silent and normal).
+  if [ -z "${owner}" ] || [ -z "${perms}" ]; then
+    logging_error "Cannot verify ownership/permissions of ${file}; refusing to source it";
+    return 1;
+  fi
+
+  # Must be owned by us or by root (root-owned system config is trusted).
+  if [ "${owner}" != "$(id -u)" ] && [ "${owner}" != "0" ]; then
+    logging_error "Ignoring config ${file}: not owned by the current user or root";
+    return 1;
+  fi
+
+  # Reject group- or world-writable files. `perms` is an octal string like
+  # "644" or "0644"; the last two characters are the group and other digits.
+  # Each is a single octal digit, so its write bit is the 2's place.
+  local group_bit="${perms: -2:1}" other_bit="${perms: -1:1}";
+  if [ "$(( 8#${group_bit:-0} & 2 ))" -ne 0 ] || [ "$(( 8#${other_bit:-0} & 2 ))" -ne 0 ]; then
+    logging_error "Ignoring config ${file}: writable by group or others (insecure permissions); run 'chmod 600 ${file}'";
+    return 1;
+  fi
+
+  return 0;
+}
+
+# _load_config_file <file> <description>
+# Source a config file only if it exists and passes the trust check.
+_load_config_file() {
+  local file="${1}" desc="${2}";
+  [ -f "${file}" ] || return 0;
+  if ! _config_is_trusted "${file}"; then
+    return 0;
+  fi
+  logging_debug "Loading config from ${file}${desc:+ }${desc}";
+  # Sourcing a user-provided config path is intentional and dynamic; the trust
+  # check above gates it. shellcheck cannot follow a non-constant source.
+  # shellcheck disable=SC1090
+  . "${file}";
+}
+
 load_config() {
   local current_env ELL_XDG_CONFIG;
   logging_debug "Storing current environment";
@@ -16,27 +74,15 @@ load_config() {
   set -o allexport;
 
   ELL_XDG_CONFIG="${XDG_CONFIG_HOME:-${HOME}/.config}/ell/config";
-  if [ -f "${ELL_XDG_CONFIG}" ]; then
-    logging_debug "Loading config from ${ELL_XDG_CONFIG} (XDG)";
-    . "${ELL_XDG_CONFIG}"
-  fi
-
-  if [ -f "${HOME}/.ellrc" ]; then
-    logging_debug "Loading config from ${HOME}/.ellrc (from \$HOME, legacy)";
-    . "${HOME}/.ellrc"
-  fi
-
-  if [ -f "${PWD}/.ellrc" ]; then
-    logging_debug "Loading config from ${PWD}/.ellrc (from \$PWD)";
-    . "${PWD}/.ellrc"
-  fi
+  _load_config_file "${ELL_XDG_CONFIG}" "(XDG)";
+  _load_config_file "${HOME}/.ellrc" "(from \$HOME, legacy)";
+  _load_config_file "${PWD}/.ellrc" "(from \$PWD)";
 
   if [ -z "${ELL_CONFIG}" ]; then
     logging_debug "ELL_CONFIG is not set";
   else
     if [ -f "${ELL_CONFIG}" ]; then
-      logging_debug "Loading config from ${ELL_CONFIG}";
-      . "${ELL_CONFIG}"
+      _load_config_file "${ELL_CONFIG}" "";
     else
       logging_fatal "Config file ${ELL_CONFIG} not found";
       exit 1;
@@ -47,4 +93,4 @@ load_config() {
   set +o allexport;
 }
 
-export load_config;
\ No newline at end of file
+export -f load_config;
\ No newline at end of file
diff --git a/helpers/load_config.test.sh b/helpers/load_config.test.sh
new file mode 100644
index 0000000..7972fc3
--- /dev/null
+++ b/helpers/load_config.test.sh
@@ -0,0 +1,188 @@
+#!/usr/bin/env bash
+
+# Self-checking tests for helpers/load_config.sh.
+#
+# Config files are *sourced*, i.e. executed as shell code, so a config file
+# that another user could plant or tamper with is an arbitrary-code-execution
+# vector (notably $PWD/.ellrc when ell is run inside an untrusted directory).
+#
+# load_config now refuses to source any config file that is not owned by the
+# current user (or root) and that is writable by group or others. These tests
+# lock in that trust check: insecure files must be skipped, secure files must
+# still load, and a missing file must be a no-op.
+
+set -o posix;
+
+DIR="$(dirname "${0}")";
+. "${DIR}/../tests/assert.sh";
+
+ELL_LOG_LEVEL=0;
+export ELL_LOG_LEVEL;
+. "${DIR}/logging.sh";
+. "${DIR}/load_config.sh";
+
+echo "load_config tests";
+echo "=================";
+
+WORK="$(mktemp -d)";
+trap 'rm -rf "${WORK}"' EXIT;
+
+# The trust check relies on POSIX permission bits (group/other write). On some
+# platforms -- notably Windows Git Bash / MSYS over NTFS -- chmod cannot create
+# a genuinely group/world-writable file and `stat` does not report those bits
+# reliably, so the "reject insecure file" path cannot be exercised there.
+# Probe once: create a world-writable file and see whether the write bits stick.
+# If they do not, the environment lacks trustworthy POSIX perms and the
+# perms-dependent assertions are SKIPped (see docs/Configuration.md, "Windows").
+posix_perms_trustworthy() {
+  local probe="${WORK}/.perm_probe" p;
+  printf '' > "${probe}";
+  chmod 666 "${probe}" 2>/dev/null || { rm -f "${probe}"; return 1; }
+  p="$(stat -c '%a' "${probe}" 2>/dev/null || stat -f '%Lp' "${probe}" 2>/dev/null)";
+  rm -f "${probe}";
+  # Expect both group (2) and other (2) write bits to be present.
+  case "${p}" in
+    *[2367][2367]) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+if posix_perms_trustworthy; then
+  PERMS_OK=true;
+else
+  PERMS_OK=false;
+fi
+
+# A file owned by us with private (0600) permissions is trusted.
+printf 'x=1\n' > "${WORK}/private";
+chmod 600 "${WORK}/private";
+assert_success "0600 file is trusted" _config_is_trusted "${WORK}/private";
+
+# 0644 (readable by all but writable only by owner) is still trusted.
+printf 'x=1\n' > "${WORK}/readable";
+chmod 644 "${WORK}/readable";
+assert_success "0644 file is trusted" _config_is_trusted "${WORK}/readable";
+
+# Group-writable and world-writable files are rejected. Only meaningful where
+# POSIX permission bits are trustworthy (see the probe above).
+if [ "${PERMS_OK}" = "true" ]; then
+  printf 'x=1\n' > "${WORK}/group_w";
+  chmod 660 "${WORK}/group_w";
+  assert_failure "group-writable file is rejected" _config_is_trusted "${WORK}/group_w";
+
+  printf 'x=1\n' > "${WORK}/world_w";
+  chmod 606 "${WORK}/world_w";
+  assert_failure "world-writable file is rejected" _config_is_trusted "${WORK}/world_w";
+else
+  echo "SKIP: group-writable file is rejected (POSIX perms not trustworthy here)";
+  echo "SKIP: world-writable file is rejected (POSIX perms not trustworthy here)";
+fi
+
+# A trusted file is actually sourced by _load_config_file.
+printf 'ELL_TEST_TRUSTED=loaded\n' > "${WORK}/trusted_cfg";
+chmod 600 "${WORK}/trusted_cfg";
+loaded="$(_load_config_file "${WORK}/trusted_cfg" "" >/dev/null 2>&1; printf '%s' "${ELL_TEST_TRUSTED}")";
+assert_equals "trusted config is sourced" "loaded" "${loaded}";
+
+# A world-writable file is NOT sourced, and refusing it is logged visibly.
+# Same POSIX-perms caveat as above.
+if [ "${PERMS_OK}" = "true" ]; then
+  printf 'ELL_TEST_EVIL=pwned\n' > "${WORK}/evil_cfg";
+  chmod 666 "${WORK}/evil_cfg";
+  skipped="$(_load_config_file "${WORK}/evil_cfg" "" >/dev/null 2>&1; printf '%s' "${ELL_TEST_EVIL-unset}")";
+  assert_equals "untrusted config is not sourced" "unset" "${skipped}";
+
+  # Refusing an insecure config must be visible at the DEFAULT log level (2):
+  # otherwise the user's config is silently ignored and looks broken. The
+  # refusal is logged at error level, so it appears at level 2 (unlike a warn
+  # at >=3).
+  reject_msg="$(
+    ELL_LOG_LEVEL=2 _config_is_trusted "${WORK}/evil_cfg" 2>&1 >/dev/null;
+  )";
+  assert_contains "insecure config refusal is visible at level 2" \
+    "${reject_msg}" "Ignoring config";
+  assert_contains "insecure config refusal suggests chmod" \
+    "${reject_msg}" "chmod 600";
+else
+  echo "SKIP: untrusted config is not sourced (POSIX perms not trustworthy here)";
+  echo "SKIP: insecure config refusal is visible at level 2 (POSIX perms not trustworthy here)";
+  echo "SKIP: insecure config refusal suggests chmod (POSIX perms not trustworthy here)";
+fi
+
+# A missing file is a silent no-op (returns success, sources nothing).
+assert_success "missing file is a no-op" _load_config_file "${WORK}/does_not_exist" "";
+
+# --- load_config() end-to-end behaviour -------------------------------------
+#
+# load_config resolves files via HOME / XDG_CONFIG_HOME / PWD / ELL_CONFIG.
+# Point HOME and XDG_CONFIG_HOME at an isolated tree so the developer's real
+# config is never read, and run load_config in a subshell so its exports and
+# option changes (allexport) do not leak between cases.
+
+HOME_DIR="${WORK}/home";
+XDG_DIR="${WORK}/xdg";
+mkdir -p "${HOME_DIR}" "${XDG_DIR}/ell";
+
+# XDG config sets a value; the legacy ~/.ellrc overrides it. Later files win.
+printf 'ELL_LLM_MODEL=from-xdg\nELL_FROM_XDG=1\n' > "${XDG_DIR}/ell/config";
+chmod 600 "${XDG_DIR}/ell/config";
+printf 'ELL_LLM_MODEL=from-home\n' > "${HOME_DIR}/.ellrc";
+chmod 600 "${HOME_DIR}/.ellrc";
+
+result="$(
+  cd "${WORK}" || exit 1;      # PWD has no .ellrc here
+  HOME="${HOME_DIR}" XDG_CONFIG_HOME="${XDG_DIR}";
+  export HOME XDG_CONFIG_HOME;
+  unset ELL_LLM_MODEL ELL_FROM_XDG;
+  load_config >/dev/null 2>&1;
+  printf '%s|%s' "${ELL_LLM_MODEL}" "${ELL_FROM_XDG}";
+)";
+assert_equals "later config overrides earlier; values are set" "from-home|1" "${result}";
+
+# Config assignments are exported (allexport), visible to child processes.
+exported="$(
+  cd "${WORK}" || exit 1;
+  HOME="${HOME_DIR}" XDG_CONFIG_HOME="${XDG_DIR}";
+  export HOME XDG_CONFIG_HOME;
+  unset ELL_FROM_XDG;
+  load_config >/dev/null 2>&1;
+  bash -c 'printf "%s" "${ELL_FROM_XDG}"';
+)";
+assert_equals "config values are exported to children" "1" "${exported}";
+
+# A variable already set in the environment must NOT be overridden by config,
+# even though the config file assigns it. This is load_config's core contract.
+preserved="$(
+  cd "${WORK}" || exit 1;
+  HOME="${HOME_DIR}" XDG_CONFIG_HOME="${XDG_DIR}";
+  ELL_LLM_MODEL=from-env;
+  export HOME XDG_CONFIG_HOME ELL_LLM_MODEL;
+  load_config >/dev/null 2>&1;
+  printf '%s' "${ELL_LLM_MODEL}";
+)";
+assert_equals "environment is not overridden by config" "from-env" "${preserved}";
+
+# An explicit ELL_CONFIG that does not exist is fatal (non-zero exit).
+# load_config calls `exit 1`, which terminates the command-substitution
+# subshell, so run it in its own subshell and inspect that subshell's status.
+(
+  cd "${WORK}" || exit 1;
+  HOME="${HOME_DIR}" XDG_CONFIG_HOME="${XDG_DIR}" ELL_CONFIG="${WORK}/nope.conf";
+  export HOME XDG_CONFIG_HOME ELL_CONFIG;
+  load_config >/dev/null 2>&1;
+);
+assert_not_equals "missing ELL_CONFIG is fatal" "0" "${?}";
+
+# An explicit, trusted ELL_CONFIG is loaded and wins over the other files.
+printf 'ELL_LLM_MODEL=from-explicit\n' > "${WORK}/explicit.conf";
+chmod 600 "${WORK}/explicit.conf";
+explicit="$(
+  cd "${WORK}" || exit 1;
+  HOME="${HOME_DIR}" XDG_CONFIG_HOME="${XDG_DIR}" ELL_CONFIG="${WORK}/explicit.conf";
+  export HOME XDG_CONFIG_HOME ELL_CONFIG;
+  unset ELL_LLM_MODEL;
+  load_config >/dev/null 2>&1;
+  printf '%s' "${ELL_LLM_MODEL}";
+)";
+assert_equals "explicit ELL_CONFIG is loaded last" "from-explicit" "${explicit}";
+
+assert_summary;
diff --git a/helpers/logging.sh b/helpers/logging.sh
index bf94ead..8b4018e 100644
--- a/helpers/logging.sh
+++ b/helpers/logging.sh
@@ -3,9 +3,39 @@
 # logging functions
 # the logs are written to stderr so that they don't interfere with pipes
 
-ELL_LOG_LEVEL="${ELL_LOG_LEVEL:-4}";
+# Default log level. ell.sh sets this to 2 before sourcing this file, so this
+# ":-2" only applies when logging.sh is sourced on its own (e.g. in tests). Keep
+# both defaults at 2 so the level is the same regardless of entry point.
+# Levels: 1 fatal, 2 error, 3 warn, 4 info, 5 debug.
+ELL_LOG_LEVEL="${ELL_LOG_LEVEL:-2}";
+# ELL_LOG_LEVEL is compared numerically with `-ge`; a non-integer value (e.g.
+# from `-l abc`) would make every comparison error out. Fall back to the default
+# if it is not a plain non-negative integer.
+case "${ELL_LOG_LEVEL}" in
+  ''|*[!0-9]*) ELL_LOG_LEVEL=2;;
+esac
+
 TO_TTY="${TO_TTY:-true}";
 
+# The program name is constant for the life of the process; compute it once
+# instead of forking basename on every log line.
+_ELL_LOG_PROG="${0##*/}";
+
+# The printf %()T time format is a bash 4.2 builtin that lets us format the
+# timestamp without forking `date`. 
+if [ "${BASH_VERSINFO[0]:-0}" -gt 4 ] \
+   || { [ "${BASH_VERSINFO[0]:-0}" -eq 4 ] && [ "${BASH_VERSINFO[1]:-0}" -ge 2 ]; }; then
+  # bash >= 4.2: format via the printf %()T builtin, no subprocess.
+  _ell_now() {
+    printf -v "${1}" '%(%Y-%m-%d %H:%M:%S)T' -1;
+  }
+else
+  # bash 4.1: fall back to forking date.
+  _ell_now() {
+    printf -v "${1}" '%s' "$(date +'%Y-%m-%d %H:%M:%S')";
+  }
+fi
+
 [ "x${TO_TTY}" = xtrue ] && LOG_STYLE_RESET="$(printf "\033[0m")" || LOG_STYLE_RESET="";
 [ "x${TO_TTY}" = xtrue ] && LOG_STYLE_PUNC="$(printf "\033[0m\033[2m")" || LOG_STYLE_PUNC="";
 [ "x${TO_TTY}" = xtrue ] && LOG_STYLE_DEBUG="$(printf "\033[97m\033[1m")" || LOG_STYLE_DEBUG="";
@@ -14,21 +44,32 @@ TO_TTY="${TO_TTY:-true}";
 [ "x${TO_TTY}" = xtrue ] && LOG_STYLE_ERROR="$(printf "\033[93m\033[1m")" || LOG_STYLE_ERROR="";
 [ "x${TO_TTY}" = xtrue ] && LOG_STYLE_FATAL="$(printf "\033[91m\033[1m")" || LOG_STYLE_FATAL="";
 
+# _ell_log_prefix: print "[<timestamp>] <prog> " to stderr. The timestamp
+# strategy (_ell_now) was chosen once at load time, so there is no per-call
+# version check here.
+_ell_log_prefix() {
+  local ts;
+  _ell_now ts;
+  printf "%s" "${LOG_STYLE_PUNC}[${LOG_STYLE_RESET}${ts}${LOG_STYLE_PUNC}]${LOG_STYLE_RESET} ${_ELL_LOG_PROG} " >&2;
+}
+
 logging_debug() {
   if [ "${ELL_LOG_LEVEL}" -ge 5 ]; then
-    echo "${LOG_STYLE_PUNC}[${LOG_STYLE_RESET}$(date +'%Y-%m-%d %H:%M:%S')${LOG_STYLE_PUNC}]${LOG_STYLE_RESET} $(basename "${0}") ${LOG_STYLE_DEBUG}DEBUG${LOG_STYLE_RESET} ${*}" >&2;
+    _ell_log_prefix;
+    echo "${LOG_STYLE_DEBUG}DEBUG${LOG_STYLE_RESET} ${*}" >&2;
   fi
 }
 
 logging_info() {
   if [ "${ELL_LOG_LEVEL}" -ge 4 ]; then
-    echo "${LOG_STYLE_PUNC}[${LOG_STYLE_RESET}$(date +'%Y-%m-%d %H:%M:%S')${LOG_STYLE_PUNC}]${LOG_STYLE_RESET} $(basename "${0}") ${LOG_STYLE_INFO}INFO${LOG_STYLE_RESET} ${*}" >&2;
+    _ell_log_prefix;
+    echo "${LOG_STYLE_INFO}INFO${LOG_STYLE_RESET} ${*}" >&2;
   fi
 }
 
 logging_warn() {
   if [ "${ELL_LOG_LEVEL}" -ge 4 ]; then
-    printf "%s" "${LOG_STYLE_PUNC}[${LOG_STYLE_RESET}$(date +'%Y-%m-%d %H:%M:%S')${LOG_STYLE_PUNC}]${LOG_STYLE_RESET} $(basename "${0}") " >&2;
+    _ell_log_prefix;
   fi
   if [ "${ELL_LOG_LEVEL}" -ge 3 ]; then
     echo "${LOG_STYLE_WARN}WARN${LOG_STYLE_RESET} ${*}" >&2;
@@ -37,7 +78,7 @@ logging_warn() {
 
 logging_error() {
   if [ "${ELL_LOG_LEVEL}" -ge 4 ]; then
-    printf "%s" "${LOG_STYLE_PUNC}[${LOG_STYLE_RESET}$(date +'%Y-%m-%d %H:%M:%S')${LOG_STYLE_PUNC}]${LOG_STYLE_RESET} $(basename "${0}") " >&2;
+    _ell_log_prefix;
   fi
   if [ "${ELL_LOG_LEVEL}" -ge 2 ]; then
     echo "${LOG_STYLE_ERROR}ERROR${LOG_STYLE_RESET} ${*}" >&2;
@@ -46,11 +87,11 @@ logging_error() {
 
 logging_fatal() {
   if [ "${ELL_LOG_LEVEL}" -ge 4 ]; then
-    printf "%s" "${LOG_STYLE_PUNC}[${LOG_STYLE_RESET}$(date +'%Y-%m-%d %H:%M:%S')${LOG_STYLE_PUNC}]${LOG_STYLE_RESET} $(basename "${0}") " >&2;
+    _ell_log_prefix;
   fi
   if [ "${ELL_LOG_LEVEL}" -ge 1 ]; then
     echo "${LOG_STYLE_FATAL}FATAL${LOG_STYLE_RESET} ${*}" >&2;
   fi
 }
 
-export logging_debug logging_info logging_warn logging_error logging_fatal;
\ No newline at end of file
+export -f _ell_now _ell_log_prefix logging_debug logging_info logging_warn logging_error logging_fatal;
diff --git a/helpers/logging.test.sh b/helpers/logging.test.sh
index 845b28b..7e4e2df 100644
--- a/helpers/logging.test.sh
+++ b/helpers/logging.test.sh
@@ -84,4 +84,63 @@ export ELL_LOG_LEVEL=5;
 stdout="$(logging_info "ON_STDOUT" 2>/dev/null)";
 assert_equals "logs never reach stdout" "" "${stdout}";
 
+# Each log line carries a [YYYY-MM-DD HH:MM:SS] timestamp (produced by the bash
+# printf %()T builtin rather than a forked `date`).
+export ELL_LOG_LEVEL=4;
+line="$({ logging_info "TSCHECK" >/dev/null; } 2>&1)";
+if printf '%s' "${line}" | grep -qE '\[[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}\]'; then
+  _assert_pass "log line has a timestamp";
+else
+  _assert_fail "log line has a timestamp";
+  echo "  line: $(_assert_show "${line}")";
+fi
+
+# A non-integer ELL_LOG_LEVEL must not break comparisons: it falls back to the
+# default (2), so error is shown, info (needs >=4) is not, and no "integer
+# expression" error is emitted. The fallback happens when logging.sh is sourced,
+# so re-source it in a subshell with a bad value.
+bad_out="$(
+  export TO_TTY=false ELL_LOG_LEVEL="not-a-number";
+  . "${DIR}/logging.sh";
+  { logging_error "ERR_AFTER_BAD"; logging_info "INFO_AFTER_BAD"; } >/dev/null 2>&1 \
+    || true;
+  { logging_error "ERR_AFTER_BAD"; logging_info "INFO_AFTER_BAD"; } 2>&1 >/dev/null;
+)";
+assert_contains     "invalid log level falls back to 2 (error shown)" "${bad_out}" "ERROR ERR_AFTER_BAD";
+assert_not_contains "invalid log level falls back to 2 (info hidden)" "${bad_out}" "INFO_AFTER_BAD";
+assert_not_contains "invalid log level does not error" "${bad_out}" "integer expression";
+
+# --- Timestamp prefix is verbose-only (>= 4), by design ---------------------
+# The timestamp/prog prefix is intentionally shown only at high verbosity
+# (level >= 4): at lower levels error/fatal print a clean "ERROR: ..."/"FATAL:
+# ..." message without timestamp noise, which is friendlier for a CLI. These
+# tests pin that intended behaviour.
+ts_re='\[[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}\]';
+
+has_prefix() {
+  printf '%s' "${1}" | grep -qE "^${ts_re}";
+}
+
+# At level 2 (default), an error message is shown but WITHOUT the prefix.
+export ELL_LOG_LEVEL=2;
+err2="$({ logging_error "E2"; } 2>&1)";
+assert_contains "error message shown at level 2" "${err2}" "ERROR E2";
+if has_prefix "${err2}"; then
+  _assert_fail "error has no timestamp prefix at level 2";
+  echo "  line: $(_assert_show "${err2}")";
+else
+  _assert_pass "error has no timestamp prefix at level 2";
+fi
+
+# At level 4+ the prefix accompanies the message.
+export ELL_LOG_LEVEL=4;
+err4="$({ logging_error "E4"; } 2>&1)";
+assert_contains "error message shown at level 4" "${err4}" "ERROR E4";
+if has_prefix "${err4}"; then
+  _assert_pass "error carries timestamp prefix at level 4";
+else
+  _assert_fail "error carries timestamp prefix at level 4";
+  echo "  line: $(_assert_show "${err4}")";
+fi
+
 assert_summary;
diff --git a/helpers/parse_arguments.sh b/helpers/parse_arguments.sh
index edcd6df..fe4d136 100644
--- a/helpers/parse_arguments.sh
+++ b/helpers/parse_arguments.sh
@@ -10,7 +10,7 @@ print_usage() {
   echo "  -f, --input-file: use file as input prompt, use - for stdin";
   echo "  -r, --record: enter record mode";
   echo "  -i, --interactive: enter interactive mode";
-  echo "  -o, --output: output to file";
+  echo "  -o, --output, --output-file: output to file";
   echo "  --api-style: api style";
   echo "  --api-key: api key (NOT recommended in multi-user environment)";
   echo "  --api-url: api url";
@@ -26,8 +26,19 @@ print_version() {
   echo "${0} $ELL_VERSION https://github.com/simonmysun/ell";
 }
 
+# _require_arg <count> <flag>: fail with a usage error unless at least <count>
+# arguments remain (i.e. the flag <flag> was actually given its value). Without
+# this, a trailing option like `ell -m` leaves only one argument, `shift 2`
+# fails, and the while loop spins forever on the same argument.
+_require_arg() {
+  if [ "${1}" -lt 2 ]; then
+    logging_fatal "Option ${2} requires an argument";
+    exit 64; # EX_USAGE
+  fi
+}
+
 parse_arguments() {
-  local other_options other_options_array option option_array key value;
+  local other_options other_options_array option key value;
   if [ ${#} -eq 0 ]; then
     if [ "x${ELL_RECORD}" = "xtrue" ]; then
       logging_debug "Record mode enabled. Context is used.";
@@ -50,40 +61,48 @@ parse_arguments() {
         exit 0;
         ;;
       -l|--log-level)
+        _require_arg ${#} "-l/--log-level";
         logging_debug "\"-l\" present in args, setting ELL_LOG_LEVEL to ${2}";
         export ELL_LOG_LEVEL="${2}";
         shift 2;
         ;;
       -m|--model)
+        _require_arg ${#} "-m/--model";
         logging_debug "\"-m\" present in args, setting ELL_LLM_MODEL to ${2}";
         export ELL_LLM_MODEL="${2}";
         shift 2;
         ;;
       -T|--template-path)
+        _require_arg ${#} "-T/--template-path";
         logging_debug "\"-T\" present in args, setting ELL_TEMPLATE_PATH to ${2}";
         export ELL_TEMPLATE_PATH="${2}";
         shift 2;
         ;;
       -t|--template)
+        _require_arg ${#} "-t/--template";
         logging_debug "\"-t\" present in args, setting ELL_TEMPLATE to ${2}";
         export ELL_TEMPLATE="${2}";
         shift 2;
         ;;
       -f|--input-file)
+        _require_arg ${#} "-f/--input-file";
         logging_debug "\"-f\" present in args, setting ELL_INPUT_FILE to ${2}";
         export ELL_INPUT_FILE="${2}";
         shift 2;
         ;;
       -r|--record)
         logging_debug "\"-r\" present in args, setting ELL_RECORD to true";
-        if [ "${ELL_RECORD}" = "xtrue" ]; then
+        if [ "x${ELL_RECORD}" = "xtrue" ]; then
           logging_fatal "Record mode already enabled";
           exit 1;
         fi
-        ELL_RECORD=true;
+        # export for consistency with the other flags (e.g. -i), so record mode
+        # is visible to child processes (notably the script-spawned session).
+        export ELL_RECORD=true;
         shift 1;
         ;;
-      -o|--output-file)
+      -o|--output|--output-file)
+        _require_arg ${#} "-o/--output";
         logging_debug "\"-o\" present in args, setting ELL_OUTPUT_FILE to ${2}";
         export ELL_OUTPUT_FILE="${2}";
         shift 2;
@@ -94,16 +113,21 @@ parse_arguments() {
         shift 1;
         ;;
       --api-style)
+        _require_arg ${#} "--api-style";
         logging_debug "\"--api-style\" present in args, setting ELL_API_STYLE to ${2}";
         export ELL_API_STYLE="${2}";
         shift 2;
         ;;
       --api-key)
-        logging_debug "\"--api-key\" present in args, setting ELL_API_KEY to ${2}";
+        _require_arg ${#} "--api-key";
+        # Never log the key value, even at debug level: it is a secret and the
+        # log may be shared or captured. Log only that it was set.
+        logging_debug "\"--api-key\" present in args, setting ELL_API_KEY (value redacted)";
         export ELL_API_KEY="${2}";
         shift 2;
         ;;
       --api-url)
+        _require_arg ${#} "--api-url";
         logging_debug "\"--api-url\" present in args, setting ELL_API_URL to ${2}";
         export ELL_API_URL="${2}";
         shift 2;
@@ -114,27 +138,34 @@ parse_arguments() {
         shift 1;
         ;;
       -c|--config)
+        _require_arg ${#} "-c/--config";
         logging_debug "\"-c\" present in args, setting ELL_CONFIG to ${2}";
         export ELL_CONFIG="${2}";
         shift 2;
         ;;
       -O|--option)
+        _require_arg ${#} "-O/--option";
         # -O A=b -O C=d,E=f
         logging_debug "\"-O\" present in args";
         other_options="${2}";
         other_options_array=();
-        IFS=',' read -r -a other_options_array <<EOF
-${other_options}
-EOF
-        echo "${other_options_array[@]}";
+        IFS=',' read -r -a other_options_array <<< "${other_options}";
         for option in "${other_options_array[@]}"; do
-          IFS='=' read -r -a option_array <<EOF
-${option}
-EOF
-          key="${option_array[0]}";
-          value="${option_array[1]}";
+          # Split only on the first "=", so values may themselves contain "=".
+          key="${option%%=*}";
+          value="${option#*=}";
+          # Reject anything that is not a valid shell variable name so the
+          # value below can never be interpreted as code (e.g. "X=$(rm -rf ~)").
+          if [ "x${key}" = "x${option}" ]; then
+            logging_error "Ignoring malformed -O option (expected KEY=VALUE): ${option}";
+            continue;
+          fi
+          if ! [[ "${key}" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; then
+            logging_error "Ignoring -O option with invalid variable name: ${key}";
+            continue;
+          fi
           logging_debug "Setting ${key} to ${value}";
-          eval "export ${key}=${value}";
+          export "${key}=${value}";
         done
         shift 2;
         ;;
diff --git a/helpers/parse_arguments.test.sh b/helpers/parse_arguments.test.sh
new file mode 100644
index 0000000..0f63217
--- /dev/null
+++ b/helpers/parse_arguments.test.sh
@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+
+# Self-checking tests for helpers/parse_arguments.sh.
+#
+# The focus here is the -O/--option handler, which used to run
+#   eval "export ${key}=${value}"
+# and was therefore a command-injection hole: `-O 'X=$(cmd)'` executed cmd.
+# It also printed the parsed options to stdout, polluting program output.
+#
+# These tests lock in the fixed behaviour:
+#   * arbitrary command substitution / metacharacters in a value are treated as
+#     literal data and never executed,
+#   * a value may itself contain '=',
+#   * malformed entries and invalid variable names are rejected, not assigned,
+#   * the parser writes nothing to stdout while handling -O.
+
+set -o posix;
+
+DIR="$(dirname "${0}")";
+. "${DIR}/../tests/assert.sh";
+
+# parse_arguments logs via logging_* and mutates the environment (export
+# USER_PROMPT and various ELL_*). Silence logging and run each scenario in a
+# subshell so assignments from one case cannot leak into the next.
+ELL_LOG_LEVEL=0;
+export ELL_LOG_LEVEL;
+. "${DIR}/logging.sh";
+. "${DIR}/parse_arguments.sh";
+
+echo "parse_arguments tests";
+echo "=====================";
+
+MARKER="${TMPDIR:-/tmp}/ell_parse_args_pwned.$$";
+rm -f "${MARKER}";
+
+# Command substitution in a -O value must NOT be executed.
+value_x="$(
+  parse_arguments -O "X=\$(touch '${MARKER}')" "prompt" >/dev/null 2>&1;
+  printf '%s' "${X}";
+)";
+if [ -e "${MARKER}" ]; then
+  _assert_fail "-O value is not executed as a command";
+  rm -f "${MARKER}";
+else
+  _assert_pass "-O value is not executed as a command";
+fi
+assert_equals "-O value kept verbatim (not evaluated)" '$(touch '"'${MARKER}'"')' "${value_x}";
+
+# Handling -O must not print anything to stdout.
+stdout="$(parse_arguments -O 'A=b' "prompt" 2>/dev/null)";
+assert_equals "-O produces no stdout" "" "${stdout}";
+
+# A normal KEY=VALUE assignment works.
+value_a="$(parse_arguments -O 'A=b' "prompt" >/dev/null 2>&1; printf '%s' "${A}")";
+assert_equals "-O assigns a simple value" "b" "${value_a}";
+
+# A single -O may carry several comma-separated pairs.
+values_cd="$(parse_arguments -O 'C=d,E=f' "prompt" >/dev/null 2>&1; printf '%s|%s' "${C}" "${E}")";
+assert_equals "-O splits comma-separated pairs" "d|f" "${values_cd}";
+
+# The value may itself contain '=' (split on the first '=' only).
+value_eq="$(parse_arguments -O 'C=d=e' "prompt" >/dev/null 2>&1; printf '%s' "${C}")";
+assert_equals "-O value may contain '='" "d=e" "${value_eq}";
+
+# An invalid variable name must be rejected, not assigned. '1bad' is not a
+# legal shell identifier, so it can never appear in the environment; the parser
+# must skip it and log an error instead of failing or assigning anything.
+bad_env="$(
+  ELL_LOG_LEVEL=0 parse_arguments -O '1bad=x' "prompt" >/dev/null 2>&1;
+  # If any assignment had leaked, a variable whose name starts with a digit
+  # cannot exist, so scan the environment for the offending value instead.
+  env | grep -c '=x$' || true;
+)";
+assert_equals "-O rejects invalid variable name" "0" "${bad_env}";
+
+# The trailing prompt is still captured correctly alongside -O.
+prompt="$(parse_arguments -O 'A=b' "hello world" >/dev/null 2>&1; printf '%s' "${USER_PROMPT}")";
+assert_equals "prompt captured with -O present" "hello world" "${prompt}";
+
+# --- Missing-argument handling ----------------------------------------------
+#
+# A value-taking option given with no value used to leave a single argument for
+# `shift 2`, which failed and made the while loop spin forever. Each such option
+# must instead exit with EX_USAGE (64) and not hang. Every check is wrapped in
+# `timeout` so a regression to the infinite loop fails loudly instead of hanging
+# the whole suite.
+missing_arg_status() {
+  # Run parse_arguments with the given args in a subshell, bounded by timeout,
+  # and print its exit status. A timeout (124) indicates the infinite-loop
+  # regression.
+  ell_timeout 5 bash -c '
+    set -o posix;
+    ELL_LOG_LEVEL=0;
+    . "'"${DIR}"'/logging.sh";
+    . "'"${DIR}"'/parse_arguments.sh";
+    parse_arguments "${@}";
+  ' _ "${@}" >/dev/null 2>&1;
+  printf '%s' "${?}";
+}
+
+for opt in -l -m -T -t -f -o --api-style --api-key --api-url -c -O; do
+  st="$(missing_arg_status "${opt}")";
+  assert_equals "missing arg for ${opt} exits 64 (no hang)" "64" "${st}";
+done
+
+# A value-taking option followed by a valid trailing value still works even when
+# it is the last option before the prompt.
+model="$(parse_arguments -m gpt-4o "hi" >/dev/null 2>&1; printf '%s' "${ELL_LLM_MODEL}")";
+assert_equals "option with value before prompt still parses" "gpt-4o" "${model}";
+
+# --- --api-key does not leak into logs --------------------------------------
+# The key must be set but must never appear in the debug log (it is a secret and
+# logs may be shared/captured). Capture stderr at max log level and assert the
+# value is absent while the variable is still set.
+key_log="$(
+  ELL_LOG_LEVEL=5 TO_TTY=false \
+  parse_arguments --api-key sk-TESTSECRET-XYZ "hi" 2>&1 >/dev/null;
+)";
+assert_not_contains "--api-key value is not logged" "${key_log}" "sk-TESTSECRET-XYZ";
+key_val="$(parse_arguments --api-key sk-TESTSECRET-XYZ "hi" >/dev/null 2>&1; printf '%s' "${ELL_API_KEY}")";
+assert_equals "--api-key still sets ELL_API_KEY" "sk-TESTSECRET-XYZ" "${key_val}";
+
+# --- -o / --output / --output-file ------------------------------------------
+# The help text documents --output while the handler historically only matched
+# --output-file, so the documented long flag was silently treated as the prompt.
+# All three spellings must now set ELL_OUTPUT_FILE.
+for oflag in -o --output --output-file; do
+  ofile="$(parse_arguments "${oflag}" /tmp/ell_out.txt "hi" >/dev/null 2>&1; printf '%s' "${ELL_OUTPUT_FILE}")";
+  assert_equals "${oflag} sets ELL_OUTPUT_FILE" "/tmp/ell_out.txt" "${ofile}";
+done
+
+# --- -r / --record ----------------------------------------------------------
+
+# A single -r sets ELL_RECORD=true and exports it (so a child process sees it).
+record_child="$(
+  parse_arguments -r "hi" >/dev/null 2>&1;
+  bash -c 'printf "%s" "${ELL_RECORD}"';
+)";
+assert_equals "-r sets and exports ELL_RECORD" "true" "${record_child}";
+
+# The "already enabled" guard must actually fire (it used to be dead code
+# because it compared against the literal "xtrue"). When ELL_RECORD is already
+# true and -r is given again, parse_arguments must exit non-zero.
+(
+  export ELL_RECORD=true;
+  parse_arguments -r "hi" >/dev/null 2>&1;
+);
+assert_not_equals "duplicate -r is rejected (guard not dead)" "0" "${?}";
+
+assert_summary;
diff --git a/helpers/piping.sh b/helpers/piping.sh
index 9cf03cc..cfdddfd 100755
--- a/helpers/piping.sh
+++ b/helpers/piping.sh
@@ -4,16 +4,28 @@
 # e.g. `piping "cat" "grep -v 'foo'" "sort"`
 
 piping() {
-  local pipes;
+  local pipes="" stage sep="";
   if [ ${#} -eq 0 ] || [ "${1}" = '' ]; then
     # logging_debug "No pipes";
     cat -;
   else
     # logging_debug "Piping: ${@}";
-    pipes="$(printf " | %s" "${@}")";
-    pipes=$(echo "$pipes" | cut -c 4-);
+    # Each argument is one pipeline stage joined with " | " and run via bash -c.
+    # A stage may be a shell command fragment with its own arguments (e.g.
+    # "tr a-z A-Z"), so stages are NOT blindly quoted. But a plugin-hook stage is
+    # a bare executable PATH that can contain spaces (list_plugin_hooks supports
+    # that); left unquoted, bash -c would word-split the path and fail to run it.
+    # Detect that case -- a stage that is itself an existing executable file --
+    # and shell-quote just those, leaving command fragments untouched.
+    for stage in "${@}"; do
+      if [ -x "${stage}" ] && [ -f "${stage}" ]; then
+        stage="$(printf '%q' "${stage}")";
+      fi
+      pipes="${pipes}${sep}${stage}";
+      sep=" | ";
+    done
     bash -c "${pipes}";
   fi
 }
 
-export piping;
\ No newline at end of file
+export -f piping;
\ No newline at end of file
diff --git a/helpers/piping.test.sh b/helpers/piping.test.sh
index fc10f98..0fff5a5 100644
--- a/helpers/piping.test.sh
+++ b/helpers/piping.test.sh
@@ -49,4 +49,19 @@ assert_equals "sort then uppercase" "$(printf 'A\nB\nC')" "${out}";
 out="$(head -c 256 < /dev/zero | tr '\0' '0' | piping inc inc inc inc inc inc inc inc inc inc inc inc)";
 assert_equals "12 stages over 256 zeros" "$(head -c 256 < /dev/zero | tr '\0' '2')" "${out}";
 
+# A plugin-hook stage whose PATH contains spaces (list_plugin_hooks supports
+# such paths) must be run as one command, not word-split. This is the regression
+# guard for piping() shell-quoting existing-executable stages.
+WORK="$(mktemp -d)";
+trap 'rm -rf "${WORK}"' EXIT;
+mkdir -p "${WORK}/dir with space";
+HOOK="${WORK}/dir with space/hook.sh";
+printf '#!/usr/bin/env bash\nsed "s/$/ HOOKED/"\n' > "${HOOK}";
+chmod +x "${HOOK}";
+out="$(printf 'x\n' | piping "${HOOK}")";
+assert_equals "hook path with spaces runs as one stage" "x HOOKED" "${out}";
+# Mixed with a command-fragment stage (which must stay unquoted / word-split).
+out="$(printf 'x\n' | piping "${HOOK}" 'tr a-z A-Z')";
+assert_equals "spaced hook then command fragment" "X HOOKED" "${out}";
+
 assert_summary;
diff --git a/helpers/render_template.sh b/helpers/render_template.sh
new file mode 100644
index 0000000..ce782f0
--- /dev/null
+++ b/helpers/render_template.sh
@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+
+# Safe template renderer.
+#
+# Templates are JSON files containing ${VAR} placeholders. They used to be
+# rendered with
+#     PAYLOAD="$(eval "cat <<EOF
+#     $(cat "${ELL_TEMPLATE_FILE}")
+#     EOF")"
+# which runs the whole template through the shell: any $(...) or backtick in a
+# template file (or arriving through USER_PROMPT / SHELL_CONTEXT) was executed
+# as code. Installing a third-party template was therefore arbitrary code
+# execution.
+#
+# render_template performs a strict, allowlist-only substitution instead. It
+# replaces exactly the placeholders ell defines, using pure bash string
+# replacement, so template contents are treated as data and never evaluated.
+# Any other ${...} sequence is left untouched.
+#
+# render_template also owns JSON escaping. String-valued placeholders
+# (USER_PROMPT, SHELL_CONTEXT, ELL_LLM_MODEL) are escaped for embedding inside a
+# JSON string, so callers pass raw text and never hand-roll `sed` escaping. This
+# means input can pass through the redaction/post_input hooks as raw multi-line
+# text first (so those hooks work correctly), and only then be escaped here.
+# Numeric/boolean placeholders are substituted verbatim so they stay valid JSON.
+
+# Placeholders substituted as JSON string values (escaped).
+ELL_TEMPLATE_STRING_VARS=(
+  ELL_LLM_MODEL
+  SHELL_CONTEXT
+  USER_PROMPT
+);
+
+# Placeholders substituted verbatim (JSON numbers / booleans).
+ELL_TEMPLATE_RAW_VARS=(
+  ELL_LLM_TEMPERATURE
+  ELL_LLM_MAX_TOKENS
+  ELL_API_STREAM
+);
+
+# _json_escape <string>
+# Print <string> escaped so it can be embedded between the double quotes of a
+# JSON string. Handles backslash, double quote, and the C0 control characters
+# that JSON requires to be escaped (\b \t \n \f \r and \u00XX for the rest).
+# Pure bash: no subprocess is spawned.
+# The C0 control characters (0x01-0x1F) as a single string, used as a bracket
+# expression to detect any that remain after the short escapes below. Computed
+# once at load time. (NUL, 0x00, cannot appear in a bash string, so it is not
+# listed.)
+_JSON_C0=$'\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f';
+
+_json_escape() {
+  local s="${1}" out="" ch rest code;
+
+  # Escape backslash first, then double quote, so later replacements do not
+  # double-escape the backslashes they introduce.
+  s="${s//\\/\\\\}";
+  s="${s//\"/\\\"}";
+  # The common control characters get their short escape form.
+  s="${s//$'\b'/\\b}";
+  s="${s//$'\f'/\\f}";
+  s="${s//$'\n'/\\n}";
+  s="${s//$'\r'/\\r}";
+  s="${s//$'\t'/\\t}";
+
+  # Any remaining C0 control characters must be \u-escaped. This needs a
+  # per-character scan, which is comparatively expensive, so only do it when at
+  # least one such character is actually present -- the overwhelmingly common
+  # case (plain text, or text whose only controls were the short-escaped ones
+  # above) takes this fast path and returns without scanning.
+  case "${s}" in
+    *[$_JSON_C0]*) ;;
+    *) printf '%s' "${s}"; return 0 ;;
+  esac
+
+  rest="${s}";
+  out="";
+  while [ -n "${rest}" ]; do
+    ch="${rest:0:1}";
+    rest="${rest:1}";
+    printf -v code '%d' "'${ch}";
+    if [ "${code}" -ge 0 ] && [ "${code}" -lt 32 ]; then
+      printf -v ch '\\u%04x' "${code}";
+    fi
+    out="${out}${ch}";
+  done
+  printf '%s' "${out}";
+}
+
+# _ell_replace_literal <haystack> <token> <value>
+# Print <haystack> with every literal occurrence of <token> replaced by the
+# literal <value>. Implemented with prefix/suffix stripping rather than
+# ${haystack//token/value} because that replacement's handling of backslashes
+# and quotes in the replacement string differs between bash 4.1, 4.2 and 5.x
+# (some versions eat "\\", others treat surrounding quotes literally). This
+# split-and-concat approach is byte-exact and identical across all of them.
+_ell_replace_literal() {
+  local haystack="${1}" token="${2}" value="${3}" out="" rest pre;
+  rest="${haystack}";
+  while true; do
+    pre="${rest%%"${token}"*}";
+    if [ "${pre}" = "${rest}" ]; then
+      # No further occurrence of the token.
+      out="${out}${rest}";
+      break;
+    fi
+    out="${out}${pre}${value}";
+    rest="${rest#*"${token}"}";
+  done
+  printf '%s' "${out}";
+}
+
+# render_template <template-file>
+# Print the template with the allowlisted ${VAR} placeholders replaced. String
+# placeholders are JSON-escaped; numeric/boolean placeholders are inserted
+# verbatim. No shell evaluation of the template is performed. Returns non-zero
+# if the file cannot be read.
+render_template() {
+  local template_file="${1}";
+  local content var value;
+
+  if [ ! -f "${template_file}" ]; then
+    return 1;
+  fi
+
+  # Slurp the file verbatim. Command substitution strips trailing newlines,
+  # which is fine: the payload is JSON consumed by curl and a trailing newline
+  # is irrelevant.
+  content="$(cat "${template_file}")";
+
+  # String placeholders: JSON-escape the value before substituting.
+  for var in "${ELL_TEMPLATE_STRING_VARS[@]}"; do
+    value="$(_json_escape "${!var}")";
+    content="$(_ell_replace_literal "${content}" "\${${var}}" "${value}")";
+  done
+
+  # Raw placeholders: inserted verbatim so JSON numbers/booleans stay valid.
+  for var in "${ELL_TEMPLATE_RAW_VARS[@]}"; do
+    value="${!var}";
+    content="$(_ell_replace_literal "${content}" "\${${var}}" "${value}")";
+  done
+
+  printf '%s\n' "${content}";
+}
+
+export -f _json_escape;
+export -f _ell_replace_literal;
+export -f render_template;
diff --git a/helpers/render_template.test.sh b/helpers/render_template.test.sh
new file mode 100644
index 0000000..38731a1
--- /dev/null
+++ b/helpers/render_template.test.sh
@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+
+# Self-checking tests for helpers/render_template.sh.
+#
+# render_template replaced an `eval "cat <<EOF ... EOF"` that ran template
+# contents (and interpolated USER_PROMPT / SHELL_CONTEXT) through the shell,
+# which was arbitrary code execution. render_template must substitute only the
+# allowlisted ${VAR} placeholders as literal data, never evaluating $(...),
+# backticks or arithmetic, and must leave unknown placeholders untouched.
+#
+# render_template also owns JSON escaping: string placeholders (USER_PROMPT,
+# SHELL_CONTEXT, ELL_LLM_MODEL) are escaped so the rendered payload is valid
+# JSON even when the value contains quotes, backslashes or newlines; numeric /
+# boolean placeholders are inserted verbatim.
+
+set -o posix;
+
+DIR="$(dirname "${0}")";
+. "${DIR}/../tests/assert.sh";
+. "${DIR}/render_template.sh";
+
+echo "render_template tests";
+echo "=====================";
+
+WORK="$(mktemp -d)";
+trap 'rm -rf "${WORK}"' EXIT;
+
+# Basic substitution of every allowlisted placeholder.
+tmpl="${WORK}/basic.json";
+printf '{"m":"${ELL_LLM_MODEL}","t":${ELL_LLM_TEMPERATURE},"n":${ELL_LLM_MAX_TOKENS},"s":${ELL_API_STREAM},"p":"${USER_PROMPT}","c":"${SHELL_CONTEXT}"}\n' > "${tmpl}";
+out="$(
+  ELL_LLM_MODEL=gpt-4o ELL_LLM_TEMPERATURE=0.6 ELL_LLM_MAX_TOKENS=4096 \
+  ELL_API_STREAM=false USER_PROMPT=hi SHELL_CONTEXT=ctx \
+  render_template "${tmpl}";
+)";
+assert_equals "all placeholders substituted" \
+  '{"m":"gpt-4o","t":0.6,"n":4096,"s":false,"p":"hi","c":"ctx"}' "${out}";
+
+# A command substitution in USER_PROMPT must be kept literal, not executed.
+MARKER="${WORK}/pwned";
+tmpl2="${WORK}/inject.json";
+printf '{"p":"${USER_PROMPT}"}\n' > "${tmpl2}";
+out="$(
+  USER_PROMPT="a \$(touch '${MARKER}') b" render_template "${tmpl2}";
+)";
+assert_success   "prompt injection is not executed" test ! -e "${MARKER}";
+assert_contains  "prompt injection kept literal" "${out}" '$(touch';
+
+# Backticks and arithmetic in a template body are not evaluated either.
+tmpl3="${WORK}/literal.json";
+printf '{"x":"`id`","y":"$((1+1))","z":"${USER_PROMPT}"}\n' > "${tmpl3}";
+out="$(USER_PROMPT=ok render_template "${tmpl3}")";
+assert_contains "backticks left literal"   "${out}" '`id`';
+assert_contains "arithmetic left literal"  "${out}" '$((1+1))';
+assert_contains "known placeholder still substituted" "${out}" '"z":"ok"';
+
+# An unknown placeholder is left untouched (not evaluated, not blanked).
+tmpl4="${WORK}/unknown.json";
+printf '{"u":"${SOME_UNKNOWN_VAR}"}\n' > "${tmpl4}";
+out="$(SOME_UNKNOWN_VAR=leaked render_template "${tmpl4}")";
+assert_equals "unknown placeholder is left verbatim" '{"u":"${SOME_UNKNOWN_VAR}"}' "${out}";
+
+# An empty variable substitutes to nothing (valid for e.g. empty SHELL_CONTEXT).
+tmpl5="${WORK}/empty.json";
+printf '{"c":"${SHELL_CONTEXT}"}\n' > "${tmpl5}";
+out="$(SHELL_CONTEXT="" render_template "${tmpl5}")";
+assert_equals "empty value substitutes to empty string" '{"c":""}' "${out}";
+
+# A missing template file returns non-zero.
+assert_failure "missing template returns non-zero" render_template "${WORK}/nope.json";
+
+# --- JSON escaping of string placeholders -----------------------------------
+. "${DIR}/json.sh";
+
+# Double quotes in a string value are escaped so the payload stays valid JSON.
+tmpl_q="${WORK}/quote.json";
+printf '{"p":"${USER_PROMPT}"}\n' > "${tmpl_q}";
+out="$(USER_PROMPT='say "hi"' render_template "${tmpl_q}")";
+assert_contains "quotes are JSON-escaped" "${out}" '\"hi\"';
+assert_success  "payload with quotes is valid JSON" json_is_valid "${out}";
+
+# Backslashes are escaped.
+out="$(USER_PROMPT='a\b' render_template "${tmpl_q}")";
+assert_contains "backslash is JSON-escaped" "${out}" 'a\\b';
+assert_success  "payload with backslash is valid JSON" json_is_valid "${out}";
+
+# Newlines in a value become \n, keeping the JSON single-line and valid.
+out="$(USER_PROMPT="$(printf 'line1\nline2')" render_template "${tmpl_q}")";
+assert_contains "newline becomes \\n" "${out}" 'line1\nline2';
+assert_success  "payload with newline is valid JSON" json_is_valid "${out}";
+
+# A value that decodes back to the original round-trips through the parser.
+out="$(USER_PROMPT='he said "x" \ y' render_template "${tmpl_q}")";
+assert_success "escaped payload parses" json_parse "${out}";
+assert_equals  "escaped value round-trips" 'he said "x" \ y' "$(json_get p)";
+
+# Numeric/boolean placeholders are NOT quoted or escaped.
+tmpl_n="${WORK}/num.json";
+printf '{"t":${ELL_LLM_TEMPERATURE},"s":${ELL_API_STREAM}}\n' > "${tmpl_n}";
+out="$(ELL_LLM_TEMPERATURE=0.6 ELL_API_STREAM=true render_template "${tmpl_n}")";
+assert_equals "numeric placeholders inserted verbatim" '{"t":0.6,"s":true}' "${out}";
+
+# --- _json_escape control characters (fast path vs \u-escape scan) ----------
+# The short escapes (\b \f \n \r \t) are handled by fast replacements; any other
+# C0 control character is \u-escaped by a per-character scan that only runs when
+# such a character is present. Cover both branches directly.
+
+# Fast path: plain text with no control chars is returned unchanged.
+assert_equals "plain text unchanged" "hello world" "$(_json_escape 'hello world')";
+
+# Short escapes are applied (fast path: no residual C0 remains to scan).
+assert_equals "newline -> backslash-n" 'a\nb' "$(_json_escape "$(printf 'a\nb')")";
+assert_equals "tab -> backslash-t"     'a\tb' "$(_json_escape "$(printf 'a\tb')")";
+
+# Scan path: a residual C0 control char (0x01) is \u-escaped, and surrounding
+# text and short escapes are preserved.
+assert_equals "0x01 -> \\u0001"        'a\u0001b' "$(_json_escape "$(printf 'a\x01b')")";
+assert_equals "ESC 0x1b -> \\u001b"    'x\u001by' "$(_json_escape "$(printf 'x\x1by')")";
+assert_equals "mixed short + \\u"      'a\n\u001bb' "$(_json_escape "$(printf 'a\n\x1bb')")";
+
+# Whatever the path, the result must be valid inside a JSON string.
+esc="$(_json_escape "$(printf 'ctrl \x01 and \x1b end')")";
+assert_success "escaped control chars form valid JSON" json_is_valid "{\"x\":\"${esc}\"}";
+
+assert_summary;
diff --git a/helpers/render_to_text.test.sh b/helpers/render_to_text.test.sh
index d0d9eaf..ab655de 100644
--- a/helpers/render_to_text.test.sh
+++ b/helpers/render_to_text.test.sh
@@ -20,11 +20,22 @@ render() {
 fail=0;
 pass=0;
 
+# Byte-exact file comparison without depending on cmp(1) (diffutils), which is
+# not present in every environment (e.g. a minimal MSYS2). Appending a sentinel
+# 'x' before the command substitution protects any trailing newlines that
+# "$(...)" would otherwise strip, so the comparison stays byte-exact.
+bytes_equal() {
+  local a b;
+  a="$(cat "${1}"; printf x)";
+  b="$(cat "${2}"; printf x)";
+  [ "${a}" = "${b}" ];
+}
+
 assert_render() {
   local name="${1}" in="${2}" exp="${3}" got;
   got="$(mktemp)";
   render < "${in}" > "${got}";
-  if cmp -s "${got}" "${exp}"; then
+  if bytes_equal "${got}" "${exp}"; then
     echo "PASS: ${name}";
     pass=$((pass + 1));
   else
diff --git a/helpers/resolve_paths.sh b/helpers/resolve_paths.sh
index 93448f2..db2512c 100644
--- a/helpers/resolve_paths.sh
+++ b/helpers/resolve_paths.sh
@@ -29,23 +29,41 @@ _ell_search_roots() {
 # set explicitly (e.g. via -T / --template-path) it is treated as a single
 # directory and takes precedence, preserving the previous behaviour.
 # Returns non-zero if no template file is found.
+#
+# The name is validated as a single path segment (no "/", not "." or ".."), so
+# it cannot traverse out of the template directories (e.g. -t ../../secret).
 resolve_template() {
-  local name="${1}" root candidate;
+  local name="${1}" root candidate dir;
+
+  case "${name}" in
+    */*|""|.|..)
+      logging_error "Invalid template name: '${name}' (must be a simple name without '/')";
+      return 1;
+      ;;
+  esac
+
   if [ -n "${ELL_TEMPLATE_PATH}" ]; then
-    candidate="${ELL_TEMPLATE_PATH}${name}.json";
+    # Normalise the directory so a trailing slash is optional: "-T dir" and
+    # "-T dir/" both work (previously only a trailing slash resolved).
+    dir="${ELL_TEMPLATE_PATH%/}";
+    candidate="${dir}/${name}.json";
     if [ -f "${candidate}" ]; then
       printf '%s' "${candidate}";
       return 0;
     fi
     return 1;
   fi
+  # Use a here-string (command substitution) rather than `< <(process
+  # substitution)`: under `set -o posix` (as the test harness sets) bash 4.1
+  # rejects process substitution as a syntax error. A here-string keeps the
+  # loop in the current shell so `return` still exits the function.
   while IFS= read -r root; do
     candidate="${root}/templates/${name}.json";
     if [ -f "${candidate}" ]; then
       printf '%s' "${candidate}";
       return 0;
     fi
-  done < <(_ell_search_roots)
+  done <<< "$(_ell_search_roots)";
   return 1;
 }
 
@@ -61,13 +79,31 @@ resolve_template() {
 # The surviving hooks are ordered by "<plugin-dir>/<hook-file>" so the numeric
 # ordering prefix (e.g. 90_pre_output.sh) is respected regardless of which
 # root a plugin lives in.
+#
+# A hook whose filename contains ".disabled" is skipped, so a plugin can be
+# turned off by renaming its script (e.g. 50_post_input.sh -> the same name
+# with a .disabled suffix). This is how the bundled redaction plugin ships:
+# disabled by default until the user removes the .disabled suffix.
 list_plugin_hooks() {
-  local suffix="${1}" root;
+  local suffix="${1}" root hook;
+  # Enable nullglob so a non-matching glob expands to nothing instead of the
+  # literal pattern, and iterate the glob directly rather than parsing `ls`
+  # output (which breaks on paths containing spaces or newlines).
+  local nullglob_was_set=0;
+  shopt -q nullglob && nullglob_was_set=1;
+  shopt -s nullglob;
   {
+    # here-string, not process substitution: bash 4.1 under `set -o posix`
+    # rejects `< <(...)` as a syntax error.
     while IFS= read -r root; do
-      ls "${root}"/plugins/*/*"${suffix}" 2>/dev/null;
-    done < <(_ell_search_roots)
+      for hook in "${root}"/plugins/*/*"${suffix}"; do
+        printf '%s\n' "${hook}";
+      done
+    done <<< "$(_ell_search_roots)";
   } | awk -F/ '
+    # Skip disabled hooks: any path component containing ".disabled".
+    $0 ~ /\.disabled(\/|$)/ { next; }
+    $NF ~ /\.disabled/ { next; }
     {
       key = $(NF-1) "/" $NF;
       if (!(key in seen)) {
@@ -76,6 +112,10 @@ list_plugin_hooks() {
       }
     }
   ' | sort | cut -f2-;
+  # Restore nullglob to its previous state so we do not change it globally.
+  if [ "${nullglob_was_set}" -eq 0 ]; then
+    shopt -u nullglob;
+  fi
 }
 
 export -f _ell_search_roots resolve_template list_plugin_hooks 2>/dev/null;
diff --git a/helpers/resolve_paths.test.sh b/helpers/resolve_paths.test.sh
new file mode 100644
index 0000000..51d542c
--- /dev/null
+++ b/helpers/resolve_paths.test.sh
@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+
+# Self-checking tests for helpers/resolve_paths.sh.
+#
+# list_plugin_hooks:
+#   * enabled hooks are discovered,
+#   * hooks carrying a ".disabled" suffix are skipped (this is how the bundled
+#     redaction plugin ships disabled by default),
+#   * duplicate <plugin-dir>/<hook-file> across roots is de-duplicated with the
+#     highest-priority root winning,
+#   * results are ordered by "<plugin-dir>/<hook-file>",
+#   * paths with spaces are handled (glob iteration, not `ls` parsing),
+#   * nullglob is restored afterwards.
+#
+# resolve_template:
+#   * a valid name resolves across the search roots,
+#   * a name containing "/" or "."/".." is rejected (no path traversal),
+#   * ELL_TEMPLATE_PATH works with or without a trailing slash.
+
+set -o posix;
+
+DIR="$(dirname "${0}")";
+. "${DIR}/../tests/assert.sh";
+
+ELL_LOG_LEVEL=0;
+export ELL_LOG_LEVEL;
+. "${DIR}/logging.sh";
+. "${DIR}/resolve_paths.sh";
+
+echo "resolve_paths / list_plugin_hooks tests";
+echo "=======================================";
+
+# Build isolated search roots so the developer's real ~/.config etc. are not
+# consulted. _ell_search_roots derives roots from these four variables.
+WORK="$(mktemp -d)";
+trap 'rm -rf "${WORK}"' EXIT;
+
+export HOME="${WORK}/home";
+export XDG_CONFIG_HOME="${WORK}/xcfg";
+export XDG_DATA_HOME="${WORK}/xdata";
+BASE_DIR="${WORK}/base";
+export BASE_DIR;
+mkdir -p "${HOME}" "${XDG_CONFIG_HOME}" "${XDG_DATA_HOME}" "${BASE_DIR}";
+
+mkplugin() {
+  # mkplugin <root> <plugin> <file>
+  mkdir -p "${1}/plugins/${2}";
+  printf '#!/usr/bin/env bash\ncat\n' > "${1}/plugins/${2}/${3}";
+  chmod +x "${1}/plugins/${2}/${3}";
+}
+
+# An enabled hook in the bundled (BASE_DIR) root.
+mkplugin "${BASE_DIR}" "alpha" "10_post_input.sh";
+# A disabled hook (redaction-style): must be skipped.
+mkplugin "${BASE_DIR}" "redaction" "50_post_input.sh.disabled";
+# Another enabled hook, higher numeric prefix -> should sort after alpha.
+mkplugin "${BASE_DIR}" "zeta" "90_post_input.sh";
+
+hooks="$(list_plugin_hooks _post_input.sh)";
+
+assert_contains     "enabled alpha hook discovered" "${hooks}" "/plugins/alpha/10_post_input.sh";
+assert_contains     "enabled zeta hook discovered"  "${hooks}" "/plugins/zeta/90_post_input.sh";
+assert_not_contains "disabled hook skipped"         "${hooks}" "redaction/50_post_input.sh.disabled";
+assert_not_contains "disabled hook not matched at all" "${hooks}" "redaction";
+
+# Ordering: alpha (10_) must come before zeta (90_).
+first_line="$(printf '%s\n' "${hooks}" | head -n 1)";
+assert_contains "alpha sorts before zeta" "${first_line}" "alpha/10_post_input.sh";
+
+# De-duplication + priority: the same plugin-dir/hook-file in a higher-priority
+# root (XDG_CONFIG_HOME) must override the bundled copy, and only one should be
+# listed.
+mkplugin "${BASE_DIR}"          "shared" "20_post_input.sh";
+mkplugin "${XDG_CONFIG_HOME}/ell" "shared" "20_post_input.sh";
+hooks="$(list_plugin_hooks _post_input.sh)";
+count="$(printf '%s\n' "${hooks}" | grep -c "shared/20_post_input.sh" || true)";
+assert_equals   "shared hook de-duplicated to one entry" "1" "${count}";
+assert_contains "shared hook resolved from XDG config (higher priority)" \
+  "${hooks}" "${XDG_CONFIG_HOME}/ell/plugins/shared/20_post_input.sh";
+assert_not_contains "bundled shared copy not used" \
+  "${hooks}" "${BASE_DIR}/plugins/shared/20_post_input.sh";
+
+# A disabled hook that is the ONLY copy of its plugin yields no entry for it.
+mkplugin "${BASE_DIR}" "onlydisabled" "30_post_input.sh.disabled";
+hooks="$(list_plugin_hooks _post_input.sh)";
+assert_not_contains "sole disabled plugin absent" "${hooks}" "onlydisabled";
+
+# A filename that both matches the hook suffix AND contains ".disabled" (either
+# in a directory component or the file name itself) must still be skipped by the
+# awk filter, not just by the glob. Directory-component case:
+mkplugin "${BASE_DIR}" "beta.disabled" "40_post_input.sh";
+# File-name case (matches "*_post_input.sh" yet is marked disabled):
+mkdir -p "${BASE_DIR}/plugins/gamma";
+printf '#!/usr/bin/env bash\ncat\n' > "${BASE_DIR}/plugins/gamma/50.disabled_post_input.sh";
+chmod +x "${BASE_DIR}/plugins/gamma/50.disabled_post_input.sh";
+hooks="$(list_plugin_hooks _post_input.sh)";
+assert_not_contains "disabled directory component skipped" "${hooks}" "beta.disabled";
+assert_not_contains "disabled filename skipped by awk filter" "${hooks}" "50.disabled_post_input.sh";
+
+# A plugin directory containing a space is handled: glob iteration keeps it in
+# one piece, whereas parsing `ls` output would have split it.
+mkplugin "${BASE_DIR}" "with space" "60_post_input.sh";
+hooks="$(list_plugin_hooks _post_input.sh)";
+assert_contains "plugin path with space discovered" "${hooks}" "with space/60_post_input.sh";
+
+# nullglob is restored to its prior (off) state after the call.
+shopt -u nullglob;
+list_plugin_hooks _post_input.sh >/dev/null;
+if shopt -q nullglob; then
+  _assert_fail "nullglob restored after list_plugin_hooks";
+else
+  _assert_pass "nullglob restored after list_plugin_hooks";
+fi
+
+# --- resolve_template -------------------------------------------------------
+
+# A template in the bundled templates/ dir resolves.
+mkdir -p "${BASE_DIR}/templates";
+printf '{}\n' > "${BASE_DIR}/templates/mytemplate.json";
+resolved="$(resolve_template "mytemplate" 2>/dev/null)";
+assert_equals "valid template resolves" "${BASE_DIR}/templates/mytemplate.json" "${resolved}";
+
+# A name that traverses out of the template dir is rejected.
+assert_failure "template traversal rejected"  resolve_template "../../etc/passwd";
+assert_failure "template with slash rejected" resolve_template "sub/dir";
+assert_failure "empty template name rejected" resolve_template "";
+assert_failure "dotdot template name rejected" resolve_template "..";
+
+# ELL_TEMPLATE_PATH resolves with and without a trailing slash.
+mkdir -p "${WORK}/tpl";
+printf '{}\n' > "${WORK}/tpl/explicit.json";
+got_noslash="$(ELL_TEMPLATE_PATH="${WORK}/tpl" resolve_template "explicit" 2>/dev/null)";
+assert_equals "ELL_TEMPLATE_PATH without trailing slash" "${WORK}/tpl/explicit.json" "${got_noslash}";
+got_slash="$(ELL_TEMPLATE_PATH="${WORK}/tpl/" resolve_template "explicit" 2>/dev/null)";
+assert_equals "ELL_TEMPLATE_PATH with trailing slash" "${WORK}/tpl/explicit.json" "${got_slash}";
+
+assert_summary;
diff --git a/llm_backends/ell_echo/generate_completion.sh b/llm_backends/ell_echo/generate_completion.sh
index be2f372..b69a660 100644
--- a/llm_backends/ell_echo/generate_completion.sh
+++ b/llm_backends/ell_echo/generate_completion.sh
@@ -6,4 +6,4 @@ generate_completion() {
   cat -;
 }
 
-export generate_completion;
\ No newline at end of file
+export -f generate_completion;
\ No newline at end of file
diff --git a/llm_backends/gemini/generate_completion.sh b/llm_backends/gemini/generate_completion.sh
index 4edeef9..5395997 100644
--- a/llm_backends/gemini/generate_completion.sh
+++ b/llm_backends/gemini/generate_completion.sh
@@ -1,138 +1,147 @@
 #!/usr/bin/env bash
 
+# ell_curl (helpers/http.sh), json_* (helpers/json.sh), logging_* and the
+# ell_backend_* helpers (helpers/backend_common.sh) are provided by ell.sh,
+# which sources the helpers before sourcing this backend.
+
 generate_completion() {
-  local response curl_status prompt_tokens completion_tokens total_tokens line stop_reason;
+  local line stop_reason;
+  # Pass the API key to curl via ELL_CURL_AUTH_HEADER (ell_curl feeds it through
+  # a --config file) so it never appears on curl's command line / process table.
+  # Only set the header when a key is actually present: an empty key must send NO
+  # api-key header (per ell.sh's preflight), not an empty "x-goog-api-key:" --
+  # which would also trip ell_curl's "refuse credential over http://" guard,
+  # which treats any non-empty auth header as a credential.
+  local ELL_CURL_AUTH_HEADER;
+  if [ -n "${ELL_API_KEY}" ]; then
+    ELL_CURL_AUTH_HEADER="x-goog-api-key: ${ELL_API_KEY}";
+    export ELL_CURL_AUTH_HEADER;
+  fi
+
   if [ "x${ELL_API_STREAM}" != "xtrue" ]; then
-    logging_debug "Streaming disabled";
-    response=$(cat - | curl "${ELL_API_URL}${ELL_LLM_MODEL}:generateContent" \
-      --silent \
-      --header "Content-Type: application/json" \
-      --header "x-goog-api-key: ${ELL_API_KEY}" \
-      --data-binary @-);
-    curl_status="${?}";
-    # Check if curl was successful
-    if [ "${curl_status}" -ne 0 ]; then
-      logging_fatal "Failed to generate completion: curl exited with ${curl_status}";
-      logging_debug "Response: ${response}";
-      return 1;
-    else
-      if ! json_parse "${response}"; then
-        logging_error "Unexpected format: ${response}";
-        return 1;
+    ell_backend_nonstreaming "${ELL_API_URL}${ELL_LLM_MODEL}:generateContent" \
+      "candidates.0.content.parts.0.text" "candidates.0.finishReason" "STOP" \
+      "usageMetadata" "usageMetadata.promptTokenCount" \
+      "usageMetadata.candidatesTokenCount" "usageMetadata.totalTokenCount";
+    return "${?}";
+  fi
+
+  # Streaming: the v1beta endpoint sends one large pretty-printed JSON array,
+  # split across many lines. Track JSON object nesting depth while scanning
+  # characters once, and json_parse a chunk only when its top-level object
+  # closes (depth back to 0) -- rather than re-parsing the whole accumulated
+  # buffer per line, which is O(n^2). Strings/escapes are honoured so braces
+  # inside text do not affect the depth.
+  local curl_pipe_status stream_status;
+  ell_curl "${ELL_API_URL}${ELL_LLM_MODEL}:streamGenerateContent" \
+    --header "Content-Type: application/json" \
+    --data-binary @- | {
+    BUFFER="";
+    depth=0;
+    in_string=false;
+    escaped=false;
+    received=0;
+    emitted=0;
+    unparsable=0;
+    bad_stop=0;
+    prompt_tokens="";
+    completion_tokens="";
+    total_tokens="";
+
+    # _gemini_emit_chunk: parse BUFFER (one complete JSON object) and emit its
+    # text / track finish reason and usage. Sets bad_stop and returns 1 on a
+    # non-STOP finish reason so the caller can stop.
+    _gemini_emit_chunk() {
+      if ! json_parse "${BUFFER}"; then
+        logging_debug "Unexpected chunk: ${BUFFER}";
+        unparsable=1;
+        return 0;
+      fi
+      if json_has "candidates.0.content.parts.0.text"; then
+        json_get "candidates.0.content.parts.0.text";
+        emitted=1;
+      fi
+      if json_has "usageMetadata"; then
+        prompt_tokens=$(json_get "usageMetadata.promptTokenCount");
+        completion_tokens=$(json_get "usageMetadata.candidatesTokenCount");
+        total_tokens=$(json_get "usageMetadata.totalTokenCount");
       fi
-      # check if finishReason is present
       if json_has "candidates.0.finishReason"; then
-        if [ "x$(json_get "candidates.0.finishReason")" != "xSTOP" ]; then
-          logging_error "Unexpected finish reason: $(json_get "candidates.0.finishReason")";
+        stop_reason=$(json_get "candidates.0.finishReason");
+        if [ "x${stop_reason}" != "xSTOP" ]; then
+          logging_error "Unexpected stop reason: ${stop_reason}";
+          bad_stop=1;
           return 1;
-        else
-          json_get "candidates.0.content.parts.0.text";
-          echo "";
-          if json_has "usageMetadata"; then
-            prompt_tokens=$(json_get "usageMetadata.promptTokenCount");
-            completion_tokens=$(json_get "usageMetadata.candidatesTokenCount");
-            total_tokens=$(json_get "usageMetadata.totalTokenCount");
-            echo '';
-            logging_info "usage: prompt_tokens=${prompt_tokens}, completion_tokens=${completion_tokens}, total_tokens=${total_tokens}";
-          fi
         fi
-      else
-        logging_error "Unexpected format: ${response}";
-        return 1;
       fi
-    fi
-  else
-    local curl_pipe_status stream_status;
-    prompt_tokens="";
-    completion_tokens=""
-    total_tokens="";
-    curl "${ELL_API_URL}${ELL_LLM_MODEL}:streamGenerateContent" \
-      --silent \
-      --header "Content-Type: application/json" \
-      --header "x-goog-api-key: ${ELL_API_KEY}" \
-      --data-binary @- | {
-      # gemni API v1beta sends a large JSON array as chunks. Here we skip the first '[' and expect the in coming chunks to be valid JSON objects until the last line;
-      read -N 1;
-      PART_FINISHED=false;
-      BUFFER="";
-      received=0;
-      emitted=0;
-      bad_stop=0;
-      while read -r line; do
-        line=$(echo "${line}" | tr -d '\r');
-        received=1;
-        if [ "x${PART_FINISHED}" = "xtrue" ] && [ "x${line}" = "x]" ]; then
-          logging_debug "End of stream";
-          break;
-        elif [ "x${PART_FINISHED}" = "xtrue" ] && [ "x${line}" = "x," ]; then
-          logging_debug "skip comma";
+      return 0;
+    }
+
+    while IFS= read -r line; do
+      # Strip CR with a bash builtin instead of `echo | tr` (a fork per line).
+      line="${line//$'\r'/}";
+      received=1;
+
+      # Scan the line character by character, tracking string state and brace
+      # depth; accumulate into BUFFER only while inside an object (depth >= 1),
+      # so array punctuation ('[', ',', ']', whitespace) is skipped.
+      i=0;
+      len="${#line}";
+      while [ "${i}" -lt "${len}" ]; do
+        ch="${line:${i}:1}";
+        i=$((i + 1));
+
+        if [ "${depth}" -ge 1 ]; then
+          BUFFER="${BUFFER}${ch}";
+        fi
+
+        if [ "x${in_string}" = "xtrue" ]; then
+          if [ "x${escaped}" = "xtrue" ]; then
+            escaped=false;
+          elif [ "x${ch}" = 'x\' ]; then
+            escaped=true;
+          elif [ "x${ch}" = 'x"' ]; then
+            in_string=false;
+          fi
           continue;
-        elif [ "x${PART_FINISHED}" = "xtrue" ]; then
-          PART_FINISHED=false;
-          BUFFER="${line}";
-        else
-          BUFFER="${BUFFER}${line}";
-          # trying to parse the buffer as JSON
-          if json_parse "${BUFFER}"; then
-            if json_has "candidates.0.content.parts.0.text"; then
-              json_get "candidates.0.content.parts.0.text";
-              emitted=1;
-            fi
-            if json_has "candidates.0.finishReason"; then
-              stop_reason=$(json_get "candidates.0.finishReason");
-              if [ "x${stop_reason}" != "xSTOP" ]; then
-                logging_error "Unexpected stop reason: ${stop_reason}";
-                bad_stop=1;
-                break;
-              fi
+        fi
+
+        case "${ch}" in
+          '"')
+            in_string=true;
+            ;;
+          '{')
+            if [ "${depth}" -eq 0 ]; then
+              BUFFER="{";
             fi
-            # check if usageMetadata is present, gemini API v1beta sends usageMetadata in every chunk
-            if json_has "usageMetadata"; then
-              prompt_tokens=$(json_get "usageMetadata.promptTokenCount");
-              completion_tokens=$(json_get "usageMetadata.candidatesTokenCount");
-              total_tokens=$(json_get "usageMetadata.totalTokenCount");
+            depth=$((depth + 1));
+            ;;
+          '}')
+            depth=$((depth - 1));
+            if [ "${depth}" -eq 0 ]; then
+              _gemini_emit_chunk || break;
+              BUFFER="";
             fi
-            PART_FINISHED=true;
-            BUFFER="";
-          fi
-        fi
+            ;;
+        esac
       done
-      logging_debug "Buffer: ${BUFFER}";
-      echo '';
-      logging_info "usage: prompt_tokens=${prompt_tokens}, completion_tokens=${completion_tokens}, total_tokens=${total_tokens}";
-      # Report a failure if nothing usable came back, instead of silently
-      # succeeding with no output.
-      if [ "${emitted}" -eq 0 ]; then
-        if [ "${received}" -eq 0 ]; then
-          logging_error "No data received from ${ELL_API_URL} (empty response)";
-        else
-          logging_error "Streaming response contained no content";
-        fi
-        exit 3;
-      fi
-      # A non-"STOP" finish reason means the completion was truncated or
-      # otherwise abnormal (e.g. MAX_TOKENS, SAFETY). Fail even if some content
-      # was emitted, matching the non-streaming path, so a truncated completion
-      # is not reported as success.
       if [ "${bad_stop}" -ne 0 ]; then
-        exit 4;
+        break;
       fi
-    }
-    # Capture the whole PIPESTATUS array at once: any later simple command
-    # (including an assignment) resets it.
-    local ps=("${PIPESTATUS[@]}");
-    curl_pipe_status="${ps[0]}";
-    stream_status="${ps[1]}";
-    # Preserve the distinct exit codes so callers can tell a curl failure (the
-    # curl exit code) from a stream-parse failure (exit 3 from the reader).
-    if [ "${curl_pipe_status}" -ne 0 ]; then
-      logging_fatal "Failed to generate completion: curl exited with ${curl_pipe_status}";
-      return "${curl_pipe_status}";
-    fi
-    if [ "${stream_status}" -ne 0 ]; then
-      return "${stream_status}";
+    done
+    logging_debug "Buffer: ${BUFFER}";
+    if [ "${emitted}" -ne 0 ]; then
+      echo '';
+      logging_info "usage: prompt_tokens=${prompt_tokens}, completion_tokens=${completion_tokens}, total_tokens=${total_tokens}";
     fi
-  fi
+    ell_backend_report_stream_end "${emitted}" "${received}" "${unparsable}" "${bad_stop}" "${ELL_API_URL}";
+  }
+  # Capture the whole PIPESTATUS array at once: any later command resets it.
+  local ps=("${PIPESTATUS[@]}");
+  curl_pipe_status="${ps[0]}";
+  stream_status="${ps[1]}";
+  ell_backend_check_pipestatus "${curl_pipe_status}" "${stream_status}";
+  return "${?}";
 }
 
-export generate_completion;
+export -f generate_completion;
diff --git a/llm_backends/generate_completion.sh b/llm_backends/generate_completion.sh
index 6f42c5f..9a49b3c 100644
--- a/llm_backends/generate_completion.sh
+++ b/llm_backends/generate_completion.sh
@@ -1,4 +1,39 @@
 #!/usr/bin/env bash
 
-# Sourcing the generate_completion.sh script according to the selected API style
-. "$(dirname ${0})/llm_backends/${ELL_API_STYLE}/generate_completion.sh";
\ No newline at end of file
+# Dispatcher: source the backend implementation selected by ELL_API_STYLE.
+#
+# ELL_API_STYLE comes from the CLI/config/environment, and it used to be
+# interpolated straight into a source path:
+#     . "$(dirname ${0})/llm_backends/${ELL_API_STYLE}/generate_completion.sh"
+# so a value like "../../tmp/evil" would source an arbitrary file as shell
+# code. Validate the style name against a strict allowlist pattern (a single
+# path segment of [A-Za-z0-9._-], no slashes and no "." / ".." traversal)
+# before using it, and resolve the backend relative to this file's own
+# directory rather than the outer script's ${0}.
+
+# Directory that contains this dispatcher and the per-style backend folders.
+# When ell.sh sources us it exports BASE_DIR (the repo root), and the backends
+# live in "${BASE_DIR}/llm_backends". When the file is sourced directly (e.g.
+# from tests) BASE_DIR may be unset, in which case this file already lives in
+# the backends directory, so dirname(BASH_SOURCE) is the correct location and
+# must not have "/llm_backends" appended again.
+if [ -n "${BASE_DIR}" ]; then
+  _ELL_BACKENDS_DIR="${BASE_DIR}/llm_backends";
+else
+  _ELL_BACKENDS_DIR="$(dirname "${BASH_SOURCE[0]}")";
+fi
+
+if ! [[ "${ELL_API_STYLE}" =~ ^[A-Za-z0-9._-]+$ ]] \
+   || [ "${ELL_API_STYLE}" = "." ] || [ "${ELL_API_STYLE}" = ".." ]; then
+  logging_fatal "Invalid ELL_API_STYLE: '${ELL_API_STYLE}' (expected a backend name like 'openai', 'gemini' or 'ell_echo')";
+  exit 1;
+fi
+
+_ELL_BACKEND_FILE="${_ELL_BACKENDS_DIR}/${ELL_API_STYLE}/generate_completion.sh";
+if [ ! -f "${_ELL_BACKEND_FILE}" ]; then
+  logging_fatal "Unknown API style '${ELL_API_STYLE}': no backend at ${_ELL_BACKEND_FILE}";
+  exit 1;
+fi
+
+# shellcheck source=/dev/null
+. "${_ELL_BACKEND_FILE}";
diff --git a/llm_backends/generate_completion.test.sh b/llm_backends/generate_completion.test.sh
new file mode 100644
index 0000000..0d141cf
--- /dev/null
+++ b/llm_backends/generate_completion.test.sh
@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+
+# Self-checking tests for llm_backends/generate_completion.sh (the dispatcher).
+#
+# The dispatcher sources a backend selected by ELL_API_STYLE. That value comes
+# from the CLI/config/environment and used to be interpolated straight into a
+# source path, so "../../tmp/evil" could source an arbitrary file as shell
+# code. These tests lock in the validation: only a simple backend name that
+# resolves to an existing backend file is accepted; slashes, "."/".." traversal
+# and unknown names are rejected, and a traversal attempt never sources the
+# targeted file.
+
+set -o posix;
+
+DIR="$(dirname "${0}")";
+. "${DIR}/../tests/assert.sh";
+
+ELL_LOG_LEVEL=0;
+export ELL_LOG_LEVEL;
+. "${DIR}/../helpers/logging.sh";
+
+# The dispatcher resolves backends relative to BASE_DIR.
+BASE_DIR="$(cd "${DIR}/.." && pwd)";
+export BASE_DIR;
+
+DISPATCH="${DIR}/generate_completion.sh";
+
+# dispatch <style>: source the dispatcher with the given ELL_API_STYLE in an
+# isolated subshell, discarding output. Returns the dispatcher's exit status.
+# Sourcing a valid backend only defines functions; it performs no network I/O.
+dispatch() (
+  ELL_API_STYLE="${1}";
+  export ELL_API_STYLE;
+  # shellcheck source=/dev/null
+  . "${DISPATCH}";
+)
+
+echo "generate_completion dispatcher tests";
+echo "====================================";
+
+# Valid, shipped backends are accepted.
+assert_success "ell_echo backend loads" dispatch "ell_echo";
+assert_success "openai backend loads" dispatch "openai";
+assert_success "gemini backend loads" dispatch "gemini";
+
+# Traversal / slash-bearing / empty names are rejected.
+assert_failure "rejects parent traversal" dispatch "../../tmp";
+assert_failure "rejects nested traversal" dispatch "../openai";
+assert_failure "rejects embedded slash" dispatch "foo/bar";
+assert_failure "rejects empty style" dispatch "";
+assert_failure "rejects '.'" dispatch ".";
+assert_failure "rejects '..'" dispatch "..";
+
+# A syntactically valid but unknown backend name is rejected.
+assert_failure "rejects unknown backend" dispatch "does_not_exist";
+
+# With BASE_DIR unset, the dispatcher must fall back to its own location
+# (dirname of BASH_SOURCE, which already is the backends directory) rather than
+# appending a spurious "/llm_backends" segment. Run from the backends directory
+# so a relative BASH_SOURCE still resolves.
+dispatch_no_base_dir() (
+  unset BASE_DIR;
+  cd "${DIR}" || exit 1;
+  ELL_API_STYLE="${1}";
+  export ELL_API_STYLE;
+  # shellcheck source=/dev/null
+  . "./generate_completion.sh";
+)
+assert_success "falls back to BASH_SOURCE dir when BASE_DIR unset" \
+  dispatch_no_base_dir "ell_echo";
+
+# A traversal attempt pointing at a real attacker-controlled file must NOT
+# source it. Plant a marker-writing "backend" directory and reference it via a
+# "../" traversal from the backends directory; the dispatcher must refuse.
+EVIL_DIR="$(mktemp -d)";
+trap 'rm -rf "${EVIL_DIR}"' EXIT;
+mkdir -p "${EVIL_DIR}/evil";
+MARKER="${EVIL_DIR}/sourced";
+printf 'printf "x" > "%s"\n' "${MARKER}" > "${EVIL_DIR}/evil/generate_completion.sh";
+# From "${BASE_DIR}/llm_backends", "../<abs-ish traversal>" would reach it if
+# traversal were allowed. Any slash-bearing value is rejected before use.
+dispatch "../${EVIL_DIR#/}/evil" >/dev/null 2>&1;
+assert_success "traversal did not source the evil file" test ! -e "${MARKER}";
+
+assert_summary;
diff --git a/llm_backends/openai/generate_completion.sh b/llm_backends/openai/generate_completion.sh
index b827b20..dbdaf55 100644
--- a/llm_backends/openai/generate_completion.sh
+++ b/llm_backends/openai/generate_completion.sh
@@ -1,34 +1,74 @@
 #!/usr/bin/env bash
 
+# ell_curl (helpers/http.sh), json_* (helpers/json.sh), logging_* and the
+# ell_backend_* helpers (helpers/backend_common.sh) are provided by ell.sh,
+# which sources the helpers before sourcing this backend.
+
 generate_completion() {
-  local response curl_status prompt_tokens completion_tokens total_tokens line json_chunk stop_reason;
+  local line json_chunk stop_reason;
+  # Pass the API key to curl via ELL_CURL_AUTH_HEADER (ell_curl feeds it through
+  # a --config file) so it never appears on curl's command line / process table.
+  # Only set the header when a key is actually present: an empty key must send NO
+  # Authorization header (per ell.sh's preflight), not "Bearer " with an empty
+  # value -- which would also trip ell_curl's "refuse credential over http://"
+  # guard since it treats any non-empty auth header as a credential.
+  local ELL_CURL_AUTH_HEADER;
+  if [ -n "${ELL_API_KEY}" ]; then
+    ELL_CURL_AUTH_HEADER="Authorization: Bearer ${ELL_API_KEY}";
+    export ELL_CURL_AUTH_HEADER;
+  fi
+
   if [ "x${ELL_API_STREAM}" != "xtrue" ]; then
-    logging_debug "Streaming disabled";
-    response=$(cat - | curl "${ELL_API_URL}" \
-      --silent \
-      --header "Content-Type: application/json" \
-      --header "Authorization: Bearer ${ELL_API_KEY}" \
-      --data-binary @-);
-    curl_status="${?}";
-    # Check if curl was successful
-    if [ "${curl_status}" -ne 0 ]; then
-      logging_fatal "Failed to generate completion: curl exited with ${curl_status}";
-      logging_debug "Response: ${response}";
-      return 1;
-    else
-      if ! json_parse "${response}"; then
-        logging_error "Unexpected format: ${response}";
-        return 1;
-      fi
-      # check if finish_reason is present
-      if json_has "choices.0.finish_reason"; then
-        if [ "x$(json_get "choices.0.finish_reason")" != "xstop" ]; then
-          logging_error "Unexpected finish reason: $(json_get "choices.0.finish_reason")";
-          return 1;
+    ell_backend_nonstreaming "${ELL_API_URL}" \
+      "choices.0.message.content" "choices.0.finish_reason" "stop" \
+      "usage" "usage.prompt_tokens" "usage.completion_tokens" "usage.total_tokens";
+    return "${?}";
+  fi
+
+  # Streaming: OpenAI uses SSE framing, one JSON object per "data: {...}" line.
+  local curl_pipe_status stream_status;
+  ell_curl "${ELL_API_URL}" \
+    --header "Content-Type: application/json" \
+    --data-binary @- | {
+    # Track whether the response carried any data chunks at all, whether any was
+    # unparsable, and whether we emitted content, so end-of-stream reporting can
+    # be specific instead of silently producing nothing.
+    received=0;
+    emitted=0;
+    unparsable=0;
+    bad_stop=0;
+    prompt_tokens="";
+    completion_tokens="";
+    total_tokens="";
+    while read -r line; do
+      if [ "x${line}" = "xdata: [DONE]" ]; then
+        break;
+      elif [[ "${line}" == "data: {"* ]]; then
+        # Data chunk. Use bash builtins (pattern match + prefix strip) instead of
+        # `echo | grep` / `echo | cut`, which forked two subprocesses per chunk.
+        received=1;
+        json_chunk="${line#data: }";
+        if ! json_parse "${json_chunk}"; then
+          logging_debug "Unexpected chunk: ${json_chunk}";
+          unparsable=1;
+          continue;
+        fi
+        if json_has "choices.0.delta.content"; then
+          json_get "choices.0.delta.content";
+          emitted=1;
         else
-          json_get "choices.0.message.content";
-          echo "";
-          if json_has "usage"; then
+          # The finish reason lives at choices.0.finish_reason (null on every
+          # intermediate chunk, set to stop/length/content_filter/... on the
+          # final one).
+          if json_has "choices.0.finish_reason"; then
+            stop_reason=$(json_get "choices.0.finish_reason");
+            if [ "x${stop_reason}" != "xstop" ]; then
+              logging_error "Unexpected stop reason: ${stop_reason}";
+              bad_stop=1;
+            fi
+            break;
+          elif json_has "usage"; then
+            # Usually the last chunk carries usage information.
             prompt_tokens=$(json_get "usage.prompt_tokens");
             completion_tokens=$(json_get "usage.completion_tokens");
             total_tokens=$(json_get "usage.total_tokens");
@@ -36,101 +76,21 @@ generate_completion() {
             logging_info "usage: prompt_tokens=${prompt_tokens}, completion_tokens=${completion_tokens}, total_tokens=${total_tokens}";
           fi
         fi
+      elif [ -z "${line}" ]; then
+        continue;
       else
-        logging_error "Unexpected format: ${response}";
-        return 1;
+        logging_debug "Unexpected line: ${line}";
+        continue;
       fi
-    fi
-  else
-    local curl_pipe_status stream_status;
-    curl "${ELL_API_URL}" \
-      --silent \
-      --header "Content-Type: application/json" \
-      --header "Authorization: Bearer ${ELL_API_KEY}" \
-      --data-binary @- | {
-      # Track whether the response carried any data chunks at all, and whether
-      # we managed to emit any content. This lets us report a clear error
-      # instead of silently producing nothing when the response is malformed.
-      received=0;
-      emitted=0;
-      unparsable=0;
-      bad_stop=0;
-      while read -r line; do
-        if [ "x${line}" = "xdata: [DONE]" ]; then
-          # End of stream
-          break;
-        elif echo "x${line}" | grep -e "^xdata: {" > /dev/null 2>&1; then
-          # Data chunk received
-          received=1;
-          json_chunk=$(echo "${line}" | cut -c 6-);
-          if ! json_parse "${json_chunk}"; then
-            logging_debug "Unexpected chunk: ${json_chunk}";
-            unparsable=1;
-            continue;
-          fi
-          if json_has "choices.0.delta.content"; then
-            json_get "choices.0.delta.content";
-            emitted=1;
-          else
-            if json_has "finish_reason"; then
-              stop_reason=$(json_get "finish_reason");
-              if [ "x${stop_reason}" != "xstop" ]; then
-                logging_error "Unexpected stop reason: ${stop_reason}";
-                bad_stop=1;
-              fi
-              break;
-            elif json_has "usage"; then
-              # Data chunk contains usage information (This is usually the last chunk)
-              prompt_tokens=$(json_get "usage.prompt_tokens");
-              completion_tokens=$(json_get "usage.completion_tokens");
-              total_tokens=$(json_get "usage.total_tokens");
-              echo '';
-              logging_info "usage: prompt_tokens=${prompt_tokens}, completion_tokens=${completion_tokens}, total_tokens=${total_tokens}";
-            fi
-          fi
-        elif [ -z "${line}" ]; then
-          # Empty line, skip
-          continue;
-        else
-          logging_debug "Unexpected line: ${line}";
-          continue;
-        fi
-      done
-      # Report a failure (via exit status) if the stream produced no usable
-      # content, so the caller does not silently succeed with empty output.
-      if [ "${emitted}" -eq 0 ]; then
-        if [ "${received}" -eq 0 ]; then
-          logging_error "No data received from ${ELL_API_URL} (empty or non-streaming response)";
-        elif [ "${unparsable}" -ne 0 ]; then
-          logging_error "Response could not be parsed as a valid streaming completion";
-        else
-          logging_error "Streaming response contained no content";
-        fi
-        exit 3;
-      fi
-      # A non-"stop" finish reason means the completion was truncated or
-      # otherwise abnormal (e.g. length, content_filter). Fail even if some
-      # content was emitted, matching the non-streaming path, so a truncated
-      # completion is not reported as success.
-      if [ "${bad_stop}" -ne 0 ]; then
-        exit 4;
-      fi
-    }
-    # Capture the whole PIPESTATUS array at once: any later simple command
-    # (including an assignment) resets it.
-    local ps=("${PIPESTATUS[@]}");
-    curl_pipe_status="${ps[0]}";
-    stream_status="${ps[1]}";
-    # Preserve the distinct exit codes so callers can tell a curl failure (the
-    # curl exit code) from a stream-parse failure (exit 3 from the reader).
-    if [ "${curl_pipe_status}" -ne 0 ]; then
-      logging_fatal "Failed to generate completion: curl exited with ${curl_pipe_status}";
-      return "${curl_pipe_status}";
-    fi
-    if [ "${stream_status}" -ne 0 ]; then
-      return "${stream_status}";
-    fi
-  fi
+    done
+    ell_backend_report_stream_end "${emitted}" "${received}" "${unparsable}" "${bad_stop}" "${ELL_API_URL}";
+  }
+  # Capture the whole PIPESTATUS array at once: any later command resets it.
+  local ps=("${PIPESTATUS[@]}");
+  curl_pipe_status="${ps[0]}";
+  stream_status="${ps[1]}";
+  ell_backend_check_pipestatus "${curl_pipe_status}" "${stream_status}";
+  return "${?}";
 }
 
-export generate_completion;
+export -f generate_completion;
diff --git a/plugins/paginator/90_pre_output.sh b/plugins/paginator/90_pre_output.sh
index 694b2b3..78c7446 100755
--- a/plugins/paginator/90_pre_output.sh
+++ b/plugins/paginator/90_pre_output.sh
@@ -6,7 +6,7 @@ get_current_column() {
   exec < /dev/tty;
   oldstty="$(stty -g)";
   stty raw -echo min 0;
-  echo -ne "\e[6n" > /dev/tty;
+  printf '\e[6n' > /dev/tty;
   # tput u7 > /dev/tty    # when TERM=xterm (and relatives)
   IFS=';' read -r -d R -a pos;
   stty "${oldstty}";
@@ -21,16 +21,16 @@ if [ "x${TO_TTY}" = "xtrue" ]; then
   LENGTH=$((COLUMNS - CURR_COL));
   LINE_NUM=1;
   while IFS= read -r -N 1 char; do
-    if [ "x${char}" = "$(printf 'x\e')" ]; then
+    if [[ "${char}" == $'\e' ]]; then
       # logging_debug "Consuming escape sequence";
       esc_seq="${char}";
       read -r -N 1 char;
       esc_seq="${esc_seq}${char}";
-      if echo "x${char}" | grep -q -E '^x(\[|\()$'; then
+      if [[ "${char}" == '[' || "${char}" == '(' ]]; then
         while true; do
           read -r -N 1 char;
           esc_seq="${esc_seq}${char}";
-          echo "${char}" | grep -q -E '[a-zA-Z]' && break;
+          [[ "${char}" == [a-zA-Z] ]] && break;
         done
       fi
       BUFFER="${BUFFER}${esc_seq}";
diff --git a/plugins/paginator/90_pre_output.test.sh b/plugins/paginator/90_pre_output.test.sh
new file mode 100644
index 0000000..2a29508
--- /dev/null
+++ b/plugins/paginator/90_pre_output.test.sh
@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+
+# Self-checking tests for plugins/paginator/90_pre_output.sh.
+#
+# The paginator is a pre_output hook. When stdout is a terminal (TO_TTY=true) it
+# paginates using the cursor position and /dev/tty, which needs a real pty and
+# is not unit-testable here. But its other, critical guarantee IS testable: when
+# stdout is not a terminal (TO_TTY=false) -- e.g. piped to a file or another
+# program -- it must pass the model output through completely untouched, never
+# swallowing, reordering or rewriting bytes.
+#
+# These tests pin that passthrough behaviour byte-for-byte.
+
+set -o posix;
+
+DIR="$(dirname "${0}")";
+. "${DIR}/../../tests/assert.sh";
+
+PAGINATOR="${DIR}/90_pre_output.sh";
+
+# page <text>: run <text> through the paginator with TO_TTY=false and print the
+# result.
+page() {
+  printf '%s' "${1}" | TO_TTY=false bash "${PAGINATOR}";
+}
+
+echo "paginator passthrough tests";
+echo "===========================";
+
+# Plain text is passed through unchanged.
+assert_equals "plain text unchanged" "hello world" "$(page 'hello world')";
+
+# Multi-line content is preserved.
+multi="$(printf 'line1\nline2\nline3')";
+assert_equals "multi-line preserved" "${multi}" "$(page "${multi}")";
+
+# ANSI escape sequences in the content are passed through, not consumed.
+ansi="$(printf '\033[1mbold\033[0m text')";
+assert_equals "ANSI content preserved" "${ansi}" "$(page "${ansi}")";
+
+# Leading/trailing whitespace and tabs survive.
+spaced="$(printf '  a\tb  ')";
+assert_equals "whitespace/tabs preserved" "${spaced}" "$(page "${spaced}")";
+
+# Byte-exact check over mixed content including blank lines, so any difference
+# (including a lost/added newline) is caught. assert_files_equal does the
+# byte-exact comparison without depending on cmp (see tests/assert.sh).
+WORK="$(mktemp -d)";
+trap 'rm -rf "${WORK}"' EXIT;
+printf 'a\tb\n\n  spaced  \nunicode: 世界 😀\n' > "${WORK}/in";
+TO_TTY=false bash "${PAGINATOR}" < "${WORK}/in" > "${WORK}/out";
+assert_files_equal "passthrough is byte-identical" "${WORK}/in" "${WORK}/out";
+
+# Empty input yields empty output (no hang, no extra bytes).
+assert_equals "empty input yields empty output" "" "$(printf '' | TO_TTY=false bash "${PAGINATOR}")";
+
+assert_summary;
diff --git a/plugins/redaction/50_post_input.sh b/plugins/redaction/50_post_input.sh
deleted file mode 100755
index ea21826..0000000
--- a/plugins/redaction/50_post_input.sh
+++ /dev/null
@@ -1,66 +0,0 @@
-#!/usr/bin/env bash
-
-. "$(dirname "${0}")/../../helpers/logging.sh";
-
-# On most Linux systems, sed is GNU sed and supports the -z option since 4.2.2 (released on 2012-12-22). In case of OS X and busybox, the -z option is not supported.
-if ! command -v sed >/dev/null 2>&1; then
-  logging_info "sed is required for redaction";
-  logging_info "GNU sed >= 4.2.2 is required for multiline redaction";
-  cat;
-fi
-
-redact_high_entropy_strings() (
-  while IFS= read -r line; do
-    for word in ${line}; do
-      # Minimum length to consider
-      if [ "${#word}" -lt 16 ]; then
-        continue;
-      fi
-      ENTROPY_THRESHOLD=4.0 # Threshold for high entropy (typical for encryption keys, tokens)
-      # Calculate entropy using Shannon's formula
-      entropy=$(echo "${word}" | awk '
-        BEGIN { FS="" }
-        {
-          for(i=1; i<=NF; i++) freq[$i]++
-          total=NF
-        }
-        END {
-          entropy=0
-          for(char in freq) {
-              p = freq[char]/total
-              entropy -= p * log(p)/log(2)
-          }
-          print entropy
-        }
-      ');
-      # logging_debug "Entropy for ${word}: ${entropy}";
-      if awk "BEGIN {exit !(${entropy} <= ${ENTROPY_THRESHOLD})}"; then
-        continue;
-      fi
-      line=$(echo "${line}" | sed -E "s/$(printf '%s\n' "${word}" | sed -e 's/[]\/$*.^[+]/\\&/g')/[HIGH ENTROPY STRING REDACTED]/g");
-    done
-    echo "$line";
-  done
-) 
-
-# multi-line pattern matches first
-(
-  # if sed support -z
-  if sed -z '' </dev/null 2>/dev/null; then
-    sed -z 's/-----BEGIN.*PRIVATE KEY-----.*-----END.*PRIVATE KEY-----/[PRIVATE KEY REDACTED]/g' `# Redact potential SSH private keys`;
-  else
-    logging_info "GNU sed >= 4.2.2 is required for multiline redaction";
-    cat;
-  fi
-) \
-| while IFS= read -r line; do
-  echo "${line}" \
-  | sed -E 's/\b[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{12}\b/[UUID REDACTED]/g' `# Redact UUIDs (both with and without dashes)` \
-  | sed -E 's/\b[0-9]{4}[-. ]?[0-9]{4}[-. ]?[0-9]{4}[-. ]?[0-9]{4}\b/[CREDIT CARD REDACTED]/g' `# Redact credit card numbers` \
-  | sed -E 's/\b[A-Za-z0-9+\/]{44,}={0,2}\b/[BASE64 KEY REDACTED]/g' `# Redact base64 strings (44+ characters, typical for private keys)` \
-  | sed -E 's/\b[0-9a-fA-F]{32,}\b/[POSSIBLE HEX KEY REDACTED]/g' `# Redact hex strings (32+ characters)` \
-  | sed -E 's/\b[0-9]{3}[-]?[0-9]{2}[-]?[0-9]{4}\b/[SSN REDACTED]/g' `# Redact SSN` \
-  | sed -E 's/\b(\+?1[-.]?)?\(?[0-9]{3}\)?[-. ]?[0-9]{3}[-. ]?[0-9]{4}\b/[PHONE REDACTED]/g' `# Redact phone numbers (various formats)` \
-  | sed -E 's/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/[EMAIL REDACTED]/g' `# Redact email addresses` \
-  | redact_high_entropy_strings;
-done
diff --git a/plugins/redaction/50_post_input.sh.disabled b/plugins/redaction/50_post_input.sh.disabled
new file mode 100755
index 0000000..b436392
--- /dev/null
+++ b/plugins/redaction/50_post_input.sh.disabled
@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+
+. "$(dirname "${0}")/../../helpers/logging.sh";
+
+# On most Linux systems, sed is GNU sed and supports the -z option since 4.2.2 (released on 2012-12-22). In case of OS X and busybox, the -z option is not supported.
+# Without sed there is nothing this plugin can redact, so pass the input
+# through untouched and stop. Falling through here would call sed anyway below.
+if ! command -v sed >/dev/null 2>&1; then
+  logging_info "sed is required for redaction; passing input through unredacted";
+  cat;
+  exit 0;
+fi
+
+redact_high_entropy_strings() (
+  while IFS= read -r line; do
+    for word in ${line}; do
+      # Minimum length to consider
+      if [ "${#word}" -lt 16 ]; then
+        continue;
+      fi
+      ENTROPY_THRESHOLD=4.0 # Threshold for high entropy (typical for encryption keys, tokens)
+      # Calculate entropy using Shannon's formula
+      entropy=$(echo "${word}" | awk '
+        BEGIN { FS="" }
+        {
+          for(i=1; i<=NF; i++) freq[$i]++
+          total=NF
+        }
+        END {
+          entropy=0
+          for(char in freq) {
+              p = freq[char]/total
+              entropy -= p * log(p)/log(2)
+          }
+          print entropy
+        }
+      ');
+      # logging_debug "Entropy for ${word}: ${entropy}";
+      if awk "BEGIN {exit !(${entropy} <= ${ENTROPY_THRESHOLD})}"; then
+        continue;
+      fi
+      line=$(echo "${line}" | sed -E "s/$(printf '%s\n' "${word}" | sed -e 's/[]\/$*.^[+]/\\&/g')/[HIGH ENTROPY STRING REDACTED]/g");
+    done
+    echo "$line";
+  done
+) 
+
+# Word-boundary syntax differs between sed implementations: GNU sed uses "\b",
+# while BSD/macOS sed uses "[[:<:]]" (start) and "[[:>:]]" (end) and treats "\b"
+# as a literal backspace, so the patterns below would never match. Probe once
+# and pick the tokens the running sed actually understands.
+if printf 'x' | sed -E 's/\bx\b/Y/' 2>/dev/null | grep -q '^Y$'; then
+  WB_L='\b'; WB_R='\b';
+elif printf 'x' | sed -E 's/[[:<:]]x[[:>:]]/Y/' 2>/dev/null | grep -q '^Y$'; then
+  WB_L='[[:<:]]'; WB_R='[[:>:]]';
+else
+  # No usable word-boundary support; fall back to no anchoring. The patterns are
+  # specific enough (length/format constrained) that this is still useful, at the
+  # cost of occasionally matching a substring inside a longer token.
+  WB_L=''; WB_R='';
+fi
+
+# multi-line pattern matches first
+(
+  # if sed support -z
+  if sed -z '' </dev/null 2>/dev/null; then
+    sed -z 's/-----BEGIN.*PRIVATE KEY-----.*-----END.*PRIVATE KEY-----/[PRIVATE KEY REDACTED]/g' `# Redact potential SSH private keys`;
+  else
+    logging_info "GNU sed >= 4.2.2 is required for multiline redaction";
+    cat;
+  fi
+) \
+| while IFS= read -r line; do
+  echo "${line}" \
+  | sed -E "s/${WB_L}[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{12}${WB_R}/[UUID REDACTED]/g" `# Redact UUIDs (both with and without dashes)` \
+  | sed -E "s/${WB_L}[0-9]{4}[-. ]?[0-9]{4}[-. ]?[0-9]{4}[-. ]?[0-9]{4}${WB_R}/[CREDIT CARD REDACTED]/g" `# Redact credit card numbers` \
+  | sed -E "s|${WB_L}[A-Za-z0-9+/]{44,}={0,2}${WB_R}|[BASE64 KEY REDACTED]|g" `# Redact base64 strings (44+ characters, typical for private keys)` \
+  | sed -E "s/${WB_L}[0-9a-fA-F]{32,}${WB_R}/[POSSIBLE HEX KEY REDACTED]/g" `# Redact hex strings (32+ characters)` \
+  | sed -E "s/${WB_L}[0-9]{3}[-]?[0-9]{2}[-]?[0-9]{4}${WB_R}/[SSN REDACTED]/g" `# Redact SSN` \
+  | sed -E "s/${WB_L}(\+?1[-.]?)?\(?[0-9]{3}\)?[-. ]?[0-9]{3}[-. ]?[0-9]{4}${WB_R}/[PHONE REDACTED]/g" `# Redact phone numbers (various formats)` \
+  | sed -E "s/${WB_L}[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}${WB_R}/[EMAIL REDACTED]/g" `# Redact email addresses` \
+  | redact_high_entropy_strings;
+done
diff --git a/plugins/redaction/50_post_input.test.sh b/plugins/redaction/50_post_input.test.sh
index f1b3410..97ded2c 100644
--- a/plugins/redaction/50_post_input.test.sh
+++ b/plugins/redaction/50_post_input.test.sh
@@ -16,7 +16,11 @@ set -o posix;
 DIR="$(dirname "${0}")";
 . "${DIR}/../../tests/assert.sh";
 
-REDACT="${DIR}/50_post_input.sh";
+# The redaction plugin ships disabled by default (it is a best-effort control
+# and can mangle input), so its script carries a .disabled suffix and is not
+# auto-discovered by list_plugin_hooks. We still exercise its behaviour
+# directly by running the .disabled script, which is a normal executable.
+REDACT="${DIR}/50_post_input.sh.disabled";
 
 # redact <text>: run one line of input through the redaction plugin and print
 # the result. stderr (plugin info logs) is discarded so it doesn't pollute the
diff --git a/plugins/syntax_highlight/50_post_llm.sh b/plugins/syntax_highlight/50_post_llm.sh
index be27e56..48f70ae 100755
--- a/plugins/syntax_highlight/50_post_llm.sh
+++ b/plugins/syntax_highlight/50_post_llm.sh
@@ -40,6 +40,19 @@ if [ "x${TO_TTY}" = "xtrue" ]; then
 
   CURRENT_LINE="";
 
+  # Regex used with bash's built-in [[ =~ ]] below. It is stored in a variable
+  # so the shell parser does not treat its backticks as command substitution
+  # when the pattern would otherwise appear inline. Matches one or two
+  # backticks (a partial or would-be code fence).
+  RE_CODE_FENCE="^\`\`?$";
+  # Run of inline-markup punctuation chars (_, ~, *, `, !, ]) — "undetermined"
+  # partial markup. Stored in a variable for the same backtick-parsing reason.
+  RE_MARKUP_RUN="^((_)|(~)|(\\*)|(\`)|(!)|(\\]))+\$";
+  # "]" not immediately followed by "(" — a link/image text close with no URL.
+  # Held in a variable so the unbalanced "(" in the bracket expression does not
+  # confuse the shell parser inside an inline [[ ... ]].
+  RE_CLOSE_NO_PAREN='^\][^(]$';
+
   current_style() {
     # Set the style based on the current state of the syntax highlighting.
     printf "%b" "${STYLE_RESET}";
@@ -87,7 +100,6 @@ if [ "x${TO_TTY}" = "xtrue" ]; then
       START_OF_LINE=true;
       START_OF_CONTENT=false;
       IN_HEADING=false;
-      IN_LIST=false;
       IN_BLOCKQUOTE=false;
       IN_BOLD=false;
       IN_ITALIC=false;
@@ -122,23 +134,21 @@ if [ "x${TO_TTY}" = "xtrue" ]; then
           printf "%s" "${buffer}";
           buffer="";
           continue;
-        elif echo "x${buffer}" | grep -E -q "^x#{1,}[[:blank:]]$" >/dev/null 2>&1; then
+        elif [[ "${buffer}" =~ ^#+[[:blank:]]$ ]]; then
           # logging_debug "Heading mode";
           printf "%s" "${STYLE_RESET}${STYLE_PUNCTUATION}${buffer%?}${STYLE_RESET}${STYLE_HEADING}";
-          buffer=$(echo "${buffer}" | awk -F '' '{print $NF}');
+          buffer="${buffer: -1}";
           IN_HEADING=true;
           START_OF_CONTENT=true;
-        elif echo "x${buffer}" | grep -E -q "^x[[:digit:]]+\.[[:space:]]$" >/dev/null 2>&1; then
+        elif [[ "${buffer}" =~ ^[[:digit:]]+\.[[:space:]]$ ]]; then
           # logging_debug "Ordered list";
           printf "%s" "${STYLE_RESET}${STYLE_LIST}${buffer%?}${STYLE_RESET}";
-          buffer=$(echo "${buffer}" | awk -F '' '{print $NF}');
-          IN_LIST=true;
+          buffer="${buffer: -1}";
           START_OF_CONTENT=true;
         elif [ "x${buffer}" = "x* " ] || [ "x${buffer}" = "x- " ] || [ "x${buffer}" = "x+ " ]; then
           # logging_debug "Unordered list";
           printf "%s" "${STYLE_RESET}${STYLE_LIST}${buffer%?}${STYLE_RESET}";
-          buffer=$(echo "${buffer}" | awk -F '' '{print $NF}');
-          IN_LIST=true;
+          buffer="${buffer: -1}";
           START_OF_CONTENT=true;
         elif [ "x${buffer}" = "x>" ]; then
           # logging_debug "Blockquote mode";
@@ -157,7 +167,11 @@ if [ "x${TO_TTY}" = "xtrue" ]; then
           printf "%s" "${STYLE_RESET}${STYLE_PUNCTUATION}${buffer}${STYLE_RESET}";
           START_OF_CONTENT=true;
           buffer="";
-        elif echo "x${buffer}" | grep -E -q "^x#{1,}$" || echo "x${buffer}" | grep -E -q "^x[[:digit:]]{1,}.?$" >/dev/null 2>&1 || echo "x${buffer}" | grep -E -q "^x(\*|\-|\+)+$" >/dev/null 2>&1 || echo "x${buffer}" | grep -E -q "^x\`\`?$" >/dev/null 2>&1 || echo "x${buffer}" | grep -E -q "^x(\_|\-|\+)+$" >/dev/null 2>&1; then
+        elif [[ "${buffer}" =~ ^#+$ ]] \
+            || [[ "${buffer}" =~ ^[[:digit:]]+.?$ ]] \
+            || [[ "${buffer}" =~ ^(\*|-|\+)+$ ]] \
+            || [[ "${buffer}" =~ ${RE_CODE_FENCE} ]] \
+            || [[ "${buffer}" =~ ^(_|-|\+)+$ ]]; then
           # logging_debug "Undetermined";
           :
         else
@@ -166,7 +180,7 @@ if [ "x${TO_TTY}" = "xtrue" ]; then
           dirty=true;
         fi
       fi
-      if [ "x${IN_CODE_BLOCK}" = "xtrue" ] && ! echo "x${buffer}" | grep -E -q "^x\`\`?$" >/dev/null 2>&1; then
+      if [ "x${IN_CODE_BLOCK}" = "xtrue" ] && ! [[ "${buffer}" =~ ${RE_CODE_FENCE} ]]; then
         # logging_debug "Code block mode";
         printf "%s" "${buffer}";
         buffer="";
@@ -202,7 +216,7 @@ if [ "x${TO_TTY}" = "xtrue" ]; then
             printf "%s" "${buffer}";
           fi
           buffer="";
-        elif echo "x${buffer}" | grep -E -q "^x\*\*\*[^\*]$|^x___[^_]$" >/dev/null 2>&1; then
+        elif [[ "${buffer}" =~ ^\*\*\*[^*]$ || "${buffer}" =~ ^___[^_]$ ]]; then
           if [ "x${IN_BOLD}" = "xtrue" ] && [ "x${IN_ITALIC}" = "xtrue" ]; then
             # logging_debug "Bold off";
             # logging_debug "Italic off";
@@ -228,9 +242,9 @@ if [ "x${TO_TTY}" = "xtrue" ]; then
             IN_ITALIC=true;
             printf "%s" "${STYLE_RESET}${STYLE_PUNCTUATION}${buffer%?}$(current_style)";
           fi
-          buffer=$(echo "${buffer}" | awk -F '' '{print $NF}');
+          buffer="${buffer: -1}";
           dirty=true;
-        elif echo "x${buffer}" | grep -E -q "^x\*\*[^\*]$|^x__[^_]$" >/dev/null 2>&1; then
+        elif [[ "${buffer}" =~ ^\*\*[^*]$ || "${buffer}" =~ ^__[^_]$ ]]; then
           if [ "x${IN_BOLD}" = "xtrue" ]; then
             # logging_debug "Bold off";
             IN_BOLD=false;
@@ -240,9 +254,9 @@ if [ "x${TO_TTY}" = "xtrue" ]; then
             IN_BOLD=true;
             printf "%s" "${STYLE_RESET}${STYLE_PUNCTUATION}${buffer%?}$(current_style)";
           fi
-          buffer=$(echo "${buffer}" | awk -F '' '{print $NF}');
+          buffer="${buffer: -1}";
           dirty=true;
-        elif echo "x${buffer}" | grep -E -q "^x\*[^\*]$|^x_[^_]$" >/dev/null 2>&1; then
+        elif [[ "${buffer}" =~ ^\*[^*]$ || "${buffer}" =~ ^_[^_]$ ]]; then
           if [ "x${IN_ITALIC}" = "xtrue" ]; then
             # logging_debug "Italic off";
             IN_ITALIC=false;
@@ -252,9 +266,9 @@ if [ "x${TO_TTY}" = "xtrue" ]; then
             IN_ITALIC=true;
             printf "%s" "${STYLE_RESET}${STYLE_PUNCTUATION}${buffer%?}$(current_style)";
           fi
-          buffer=$(echo "${buffer}" | awk -F '' '{print $NF}');
+          buffer="${buffer: -1}";
           dirty=true;
-        elif echo "x${buffer}" | grep -E -q "^x~~[^~]$" >/dev/null 2>&1; then
+        elif [[ "${buffer}" =~ ^~~[^~]$ ]]; then
           if [ "x${IN_STRIKETHROUGH}" = "xtrue" ]; then
             # logging_debug "Strikethrough off";
             IN_STRIKETHROUGH=false;
@@ -264,24 +278,24 @@ if [ "x${TO_TTY}" = "xtrue" ]; then
             IN_STRIKETHROUGH=true;
             printf "%s" "${STYLE_RESET}${STYLE_PUNCTUATION}${buffer%?}$(current_style)";
           fi
-          buffer=$(echo "${buffer}" | awk -F '' '{print $NF}');
+          buffer="${buffer: -1}";
           dirty=true;
         elif [ "x${buffer}" = "x\`" ]; then
           IN_CODE=true;
           printf "%s" "${STYLE_RESET}${STYLE_PUNCTUATION}${buffer}${STYLE_RESET}${STYLE_CODE}";
           buffer="";
-        elif echo "x${buffer}" | grep -E -q "^x][^\(]$" >/dev/null 2>&1; then
+        elif [[ "${buffer}" =~ ${RE_CLOSE_NO_PAREN} ]]; then
           if [ "x${IN_LINK_TEXT}" = "xtrue" ]; then
             IN_LINK_TEXT=false;
             # logging_debug "Exit link text mode missing URL";
             printf "%s" "${STYLE_RESET}${STYLE_PUNCTUATION}${buffer%?}$(current_style)";
-            buffer=$(echo "${buffer}" | awk -F '' '{print $NF}');
+            buffer="${buffer: -1}";
             dirty=true;
           elif [ "x${IN_IMAGE_TEXT}" = "xtrue" ]; then
             IN_LINK_TEXT=false;
             # logging_debug "Exit link text mode missing URL";
             printf "%s" "${STYLE_RESET}${STYLE_PUNCTUATION}${buffer%?}$(current_style)";
-            buffer=$(echo "${buffer}" | awk -F '' '{print $NF}');
+            buffer="${buffer: -1}";
             dirty=true;
           else
             # logging_debug "']' in the wild";
@@ -329,7 +343,7 @@ if [ "x${TO_TTY}" = "xtrue" ]; then
           IN_IMAGE_TEXT=true;
           printf "%s" "${STYLE_RESET}${STYLE_PUNCTUATION}${buffer}$(current_style)";
           buffer="";
-        elif echo "x${buffer}" | grep -E -q "^x((_)|(~)|(\*)|(\`)|(\!)|(]))+$" >/dev/null 2>&1; then
+        elif [[ "${buffer}" =~ ${RE_MARKUP_RUN} ]]; then
           # logging_debug "Undetermined";
           :
         else
diff --git a/plugins/syntax_highlight/50_post_llm.test.sh b/plugins/syntax_highlight/50_post_llm.test.sh
new file mode 100644
index 0000000..e104a3a
--- /dev/null
+++ b/plugins/syntax_highlight/50_post_llm.test.sh
@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+
+# Self-checking tests for plugins/syntax_highlight/50_post_llm.sh.
+#
+# This plugin is a streaming, best-effort Markdown highlighter. It only does
+# anything when TO_TTY=true; otherwise it is a transparent `cat -`. It is by far
+# the largest file in the repo and had no tests, so a regression in the state
+# machine could silently corrupt or drop output.
+#
+# Rather than assert exact ANSI escape sequences, we override the STYLE_* hooks
+# with easy-to-spot text markers (e.g. STYLE_HEADING="<H>") and assert:
+#   * the visible text of the input is always preserved,
+#   * each construct (heading, list, bold/italic, strikethrough, inline code,
+#     code block, link) is wrapped in the corresponding style marker,
+#   * plain text is not decorated with content markers,
+#   * inside a fenced code block Markdown is NOT interpreted,
+#   * with TO_TTY=false the input passes through byte-for-byte.
+
+set -o posix;
+
+DIR="$(dirname "${0}")";
+. "${DIR}/../../tests/assert.sh";
+
+HL="${DIR}/50_post_llm.sh";
+
+# hl <input>: run the highlighter with TO_TTY=true and marker styles, printing
+# the highlighted output. Markers are plain text so output is easy to assert on.
+hl() {
+  printf '%s' "${1}" | \
+  TO_TTY=true \
+  STYLE_RESET='<R>' STYLE_HEADING='<H>' STYLE_LIST='<L>' STYLE_CODE='<C>' \
+  STYLE_CODE_BLOCK='<CB>' STYLE_BLOCKQUOTE='<BQ>' STYLE_BOLD='<B>' STYLE_ITALIC='<I>' \
+  STYLE_STRIKETHROUGH='<S>' STYLE_LINK_TEXT='<LT>' STYLE_URL='<U>' STYLE_TITLE='<T>' \
+  STYLE_IMAGE_TEXT='<IMG>' STYLE_PUNCTUATION='<P>' \
+    bash "${HL}";
+}
+
+echo "syntax_highlight tests";
+echo "======================";
+
+# --- Heading ----------------------------------------------------------------
+out="$(hl "$(printf '# Title\n')")";
+assert_contains "heading text preserved"     "${out}" "Title";
+assert_contains "heading style applied"      "${out}" "<H>";
+
+# --- Unordered list ---------------------------------------------------------
+out="$(hl "$(printf -- '- item\n')")";
+assert_contains "list text preserved"        "${out}" "item";
+assert_contains "list marker styled"         "${out}" "<L>";
+
+# --- Ordered list -----------------------------------------------------------
+out="$(hl "$(printf '1. first\n')")";
+assert_contains "ordered list text preserved" "${out}" "first";
+assert_contains "ordered list marker styled"  "${out}" "<L>";
+
+# --- Bold -------------------------------------------------------------------
+out="$(hl "$(printf 'a **bold** b\n')")";
+assert_contains "bold text preserved"        "${out}" "bold";
+assert_contains "surrounding text preserved" "${out}" "a ";
+assert_contains "bold style applied"         "${out}" "<B>";
+
+# --- Italic -----------------------------------------------------------------
+out="$(hl "$(printf 'a *it* b\n')")";
+assert_contains "italic text preserved"      "${out}" "it";
+assert_contains "italic style applied"       "${out}" "<I>";
+
+# --- Strikethrough ----------------------------------------------------------
+out="$(hl "$(printf 'a ~~gone~~ b\n')")";
+assert_contains "strikethrough text preserved" "${out}" "gone";
+assert_contains "strikethrough style applied"  "${out}" "<S>";
+
+# --- Inline code ------------------------------------------------------------
+out="$(hl "$(printf 'use `code` now\n')")";
+assert_contains "inline code text preserved" "${out}" "code";
+assert_contains "inline code style applied"  "${out}" "<C>";
+
+# --- Link -------------------------------------------------------------------
+out="$(hl "$(printf '[text](http://x)\n')")";
+assert_contains "link text preserved"        "${out}" "text";
+assert_contains "link url preserved"         "${out}" "http://x";
+assert_contains "link text style applied"    "${out}" "<LT>";
+assert_contains "link url style applied"     "${out}" "<U>";
+
+# --- Plain text is not decorated --------------------------------------------
+out="$(hl "$(printf 'plain text\n')")";
+assert_contains "plain text preserved"       "${out}" "plain text";
+assert_not_contains "no heading style on plain" "${out}" "<H>";
+assert_not_contains "no bold style on plain"    "${out}" "<B>";
+assert_not_contains "no code style on plain"    "${out}" "<C>";
+
+# --- Fenced code block: Markdown inside is NOT interpreted ------------------
+out="$(hl "$(printf '```\n**not bold**\n```\n')")";
+assert_contains "code block content preserved"   "${out}" "**not bold**";
+assert_not_contains "no bold style inside code block" "${out}" "<B>";
+assert_contains "code block style applied"       "${out}" "<CB>";
+
+# --- Escaped markdown -------------------------------------------------------
+# A backslash-escaped asterisk should not start bold; the literal * survives.
+out="$(hl "$(printf 'a \\* b\n')")";
+assert_contains "escaped asterisk survives"  "${out}" "*";
+assert_not_contains "escaped asterisk not bold" "${out}" "<B>";
+
+# --- TO_TTY=false is a transparent passthrough ------------------------------
+raw="$(printf '# Title with **bold** and `code`\n')";
+out="$(printf '%s' "${raw}" | TO_TTY=false bash "${HL}")";
+assert_equals "passthrough is byte-for-byte" "${raw}" "${out}";
+
+assert_summary;
diff --git a/tests/assert.sh b/tests/assert.sh
index dd0307e..044827e 100644
--- a/tests/assert.sh
+++ b/tests/assert.sh
@@ -25,11 +25,53 @@
 _ASSERT_PASS=0;
 _ASSERT_FAIL=0;
 
+# ell_timeout <seconds> <command...>
+# Run <command...> under `timeout`, scaling the wall-clock budget by
+# ELL_TEST_TIMEOUT_SCALE (default 1). Tests use short fixed budgets purely to
+# catch hangs (infinite loops / EOF regressions), not to measure speed, so on a
+# slow or heavily-loaded runner a genuinely-working path could otherwise exceed
+# the budget and fail with 124. Set e.g. ELL_TEST_TIMEOUT_SCALE=3 there to widen
+# every budget at once. If `timeout` is unavailable, the command is run directly
+# (no hang protection, but the suite still works).
+ell_timeout() {
+  local secs="${1}";
+  shift;
+  local scale="${ELL_TEST_TIMEOUT_SCALE:-1}";
+  # Integer-multiply the budget by the scale (both are plain integers).
+  case "${scale}${secs}" in
+    *[!0-9]*) scale=1 ;;  # non-integer scale/secs: fall back to no scaling
+  esac
+  local budget=$(( secs * scale ));
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "${budget}" "${@}";
+  else
+    "${@}";
+  fi
+}
+
 # _assert_show: render a value with control characters made visible.
 _assert_show() {
   printf '%s' "${1}" | cat -v;
 }
 
+# assert_files_equal <name> <file-a> <file-b>: byte-exact comparison of two
+# files without depending on cmp(1)/diff (diffutils), which is absent in some
+# environments (e.g. a minimal MSYS2). Appending a sentinel 'x' before the
+# command substitution preserves any trailing newlines that "$(...)" would
+# strip, keeping the comparison byte-exact.
+assert_files_equal() {
+  local name="${1}" a b;
+  a="$(cat "${2}"; printf x)";
+  b="$(cat "${3}"; printf x)";
+  if [ "${a}" = "${b}" ]; then
+    _assert_pass "${name}";
+  else
+    _assert_fail "${name}";
+    echo "  expected: $(_assert_show "$(cat "${2}")")";
+    echo "  actual  : $(_assert_show "$(cat "${3}")")";
+  fi
+}
+
 # _assert_pass / _assert_fail: record a result and print one status line.
 _assert_pass() {
   _ASSERT_PASS=$((_ASSERT_PASS + 1));
@@ -140,6 +182,46 @@ assert_failure() {
   fi
 }
 
+# assert_matches <name> <string> <regex>
+# Succeeds if <string> matches the extended regular expression <regex>. Uses
+# bash's [[ =~ ]], so no external grep is spawned; the regex is unanchored
+# (add ^...$ yourself for a full-string match).
+assert_matches() {
+  local name="${1}" string="${2}" regex="${3}";
+  # The regex must be unquoted for [[ =~ ]] to treat it as a pattern.
+  if [[ "${string}" =~ ${regex} ]]; then
+    _assert_pass "${name}";
+  else
+    _assert_fail "${name}";
+    echo "  regex : $(_assert_show "${regex}")";
+    echo "  string: $(_assert_show "${string}")";
+  fi
+}
+
+# assert_exits <name> <expected-status> -- <command...>
+# Runs <command...> and passes if it exits with <expected-status>. Both stdout
+# and stderr are discarded. This captures the status safely (a hazard when
+# hand-written, since any command before reading $? overwrites it) and removes
+# the repeated `cmd >/dev/null 2>&1; status="${?}"` boilerplate. The literal
+# `--` separates the expected status from the command for readability.
+assert_exits() {
+  local name="${1}" expected="${2}";
+  shift 2;
+  if [ "x${1}" = "x--" ]; then
+    shift;
+  fi
+  local status;
+  "${@}" >/dev/null 2>&1;
+  status="${?}";
+  if [ "${status}" -eq "${expected}" ]; then
+    _assert_pass "${name}";
+  else
+    _assert_fail "${name}";
+    echo "  expected exit: ${expected}";
+    echo "  actual exit  : ${status} (${*})";
+  fi
+}
+
 # assert_summary
 # Prints the pass/fail tally and returns non-zero if any assertion failed.
 # Call this as the final line of a test script and rely on its exit status.
diff --git a/tests/assert_lib.test.sh b/tests/assert_lib.test.sh
new file mode 100644
index 0000000..8bd9df6
--- /dev/null
+++ b/tests/assert_lib.test.sh
@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+
+# Meta-tests for the assertion library itself (tests/assert.sh), covering the
+# newer helpers assert_matches and assert_exits. The library is the foundation
+# of every other test, so a regression in it could silently make assertions
+# pass when they should fail. We exercise each helper in an isolated subshell
+# and check whether it reports PASS or FAIL, rather than trusting it on itself.
+
+set -o posix;
+
+DIR="$(cd "$(dirname "${0}")" && pwd)";
+. "${DIR}/assert.sh";
+
+META_OUT="$(mktemp)";
+trap 'rm -f "${META_OUT}"' EXIT;
+
+# run_assert <helper-and-args...>: run one assertion helper in a clean subshell
+# (fresh counters) and print the single PASS/FAIL word it emitted.
+run_assert() {
+  (
+    _ASSERT_PASS=0; _ASSERT_FAIL=0;
+    "${@}" >"${META_OUT}" 2>&1;
+    # The helper printed "PASS: ..." or "FAIL: ..." as its first line.
+    head -n1 "${META_OUT}" | cut -d: -f1;
+  );
+}
+
+echo "assert library meta-tests";
+echo "=========================";
+
+# --- assert_matches ---------------------------------------------------------
+assert_equals "matches: anchored timestamp regex" "PASS" \
+  "$(run_assert assert_matches n '[2026-01-02 03:04:05]' '^\[[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}\]')";
+assert_equals "matches: simple pattern present" "PASS" \
+  "$(run_assert assert_matches n 'error: boom' 'err(or)?:')";
+assert_equals "matches: non-matching fails" "FAIL" \
+  "$(run_assert assert_matches n 'hello' '^world$')";
+# A regex metacharacter behaves as a pattern (not a literal), unlike the
+# literal substring helpers.
+assert_equals "matches: dot is a metachar" "PASS" \
+  "$(run_assert assert_matches n 'axc' 'a.c')";
+
+# --- assert_exits -----------------------------------------------------------
+assert_equals "exits: true is 0" "PASS" \
+  "$(run_assert assert_exits n 0 -- true)";
+assert_equals "exits: false is 1" "PASS" \
+  "$(run_assert assert_exits n 1 -- false)";
+assert_equals "exits: wrong code fails" "FAIL" \
+  "$(run_assert assert_exits n 0 -- false)";
+# The `--` separator is optional.
+assert_equals "exits: works without --" "PASS" \
+  "$(run_assert assert_exits n 0 true)";
+# A specific non-zero status is matched exactly.
+assert_equals "exits: exact non-zero status" "PASS" \
+  "$(run_assert assert_exits n 3 -- sh -c 'exit 3')";
+
+# --- ell_timeout ------------------------------------------------------------
+# Only run these where `timeout` exists (ell_timeout runs the command directly
+# otherwise, which would make the "budget too small" case hang).
+#
+# A timed-out command exits non-zero, but the exact code differs: GNU coreutils
+# `timeout` returns 124, while busybox `timeout` (alpine) kills with SIGTERM and
+# returns 143. So "timed out" is asserted as "non-zero", and completion within
+# budget as the command's own status.
+if command -v timeout >/dev/null 2>&1; then
+  # Budget too small: a 2s sleep under a 1s budget times out (non-zero).
+  ELL_TEST_TIMEOUT_SCALE=1 ell_timeout 1 sleep 2 >/dev/null 2>&1;
+  assert_not_equals "ell_timeout enforces the budget" "0" "${?}";
+
+  # Scaling widens the budget: the same sleep under 1s*3 completes (0).
+  ELL_TEST_TIMEOUT_SCALE=3 ell_timeout 1 sleep 2 >/dev/null 2>&1;
+  assert_equals "ELL_TEST_TIMEOUT_SCALE widens the budget" "0" "${?}";
+
+  # A non-integer scale falls back to no scaling (budget stays 1s -> times out).
+  ELL_TEST_TIMEOUT_SCALE=abc ell_timeout 1 sleep 2 >/dev/null 2>&1;
+  assert_not_equals "invalid scale falls back to 1" "0" "${?}";
+
+  # A command that finishes within budget returns its own status.
+  ell_timeout 5 sh -c 'exit 7' >/dev/null 2>&1;
+  assert_equals "ell_timeout preserves the command's status" "7" "${?}";
+else
+  echo "SKIP: ell_timeout budget tests (timeout not available)";
+fi
+
+assert_summary;
diff --git a/tests/bash_version.sh b/tests/bash_version.sh
new file mode 100644
index 0000000..29c5ca6
--- /dev/null
+++ b/tests/bash_version.sh
@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+
+# Tests for ell.sh's bash version gate (the check at the very top of ell.sh).
+#
+# ell requires bash >= 4.1. The guard is:
+#   if [ "${BASH_VERSINFO:-0}" -ge 4 ]; then
+#     if [ "${BASH_VERSINFO:-0}" -eq 4 ] && [ "${BASH_VERSINFO[1]:-0}" -lt 1 ]; then
+#       ...reject...
+#   else ...reject... fi
+#
+# BASH_VERSINFO is read-only so we cannot fake an old bash in-process. Instead we
+# (1) replicate the exact predicate and assert its accept/reject decision for a
+# range of (major, minor) versions, (2) confirm the real ell running under the
+# current (supported) bash is not rejected, and (3) confirm the error message
+# and exit code match what ell.sh emits.
+
+set -o posix;
+
+DIR="$(cd "$(dirname "${0}")" && pwd)";
+. "${DIR}/assert.sh";
+
+# version_ok <major> <minor>: mirror of ell.sh's gate. Returns 0 (accept) if the
+# version is supported (>= 4.1), non-zero (reject) otherwise.
+version_ok() {
+  local major="${1}" minor="${2}";
+  if [ "${major}" -ge 4 ]; then
+    if [ "${major}" -eq 4 ] && [ "${minor}" -lt 1 ]; then
+      return 1;
+    fi
+  else
+    return 1;
+  fi
+  return 0;
+}
+
+echo "bash version gate tests";
+echo "=======================";
+
+# Supported: 4.1 and up.
+assert_success "4.1 accepted"  version_ok 4 1;
+assert_success "4.2 accepted"  version_ok 4 2;
+assert_success "5.0 accepted"  version_ok 5 0;
+assert_success "5.2 accepted"  version_ok 5 2;
+assert_success "6.0 accepted"  version_ok 6 0;
+
+# Unsupported: below 4.1.
+assert_failure "4.0 rejected"  version_ok 4 0;
+assert_failure "3.2 rejected"  version_ok 3 2;
+assert_failure "2.05 rejected" version_ok 2 5;
+assert_failure "0 rejected"    version_ok 0 0;
+
+# The real ell, under the current (supported) bash, must not be rejected by the
+# version gate: `--version` should succeed and print the version line.
+ver_out="$("${DIR}/../ell" --version 2>&1)";
+ver_status="${?}";
+assert_equals   "ell --version exits 0 on supported bash" "0" "${ver_status}";
+assert_contains "ell --version prints the version"        "${ver_out}" "${ELL_VERSION:-0.1.1}";
+assert_not_contains "supported bash is not rejected"      "${ver_out}" "is required to run";
+
+# The rejection message (as written in ell.sh) names 4.1, matching README/CI.
+gate_msg="$(grep -m1 'is required to run this script' "${DIR}/../ell.sh")";
+assert_contains "version message says 4.1" "${gate_msg}" "4.1 or higher";
+assert_not_contains "version message does not say 4.2" "${gate_msg}" "4.2";
+
+assert_summary;
diff --git a/tests/entry.sh b/tests/entry.sh
index 8a61fd7..086e192 100644
--- a/tests/entry.sh
+++ b/tests/entry.sh
@@ -19,10 +19,26 @@ TESTS_DIR="$(cd "$(dirname "${0}")" && pwd)";
 REPO_DIR="$(cd "${TESTS_DIR}/.." && pwd)";
 
 echo "Setting up prerequisites...";
-# curl is only needed on the minimal bash:* (alpine) images; ignore failures on
-# environments where it is already present or apk is unavailable.
+# On the minimal bash:* (alpine) images several tools the suite needs are not
+# preinstalled. Install them via apk so the container can run the FULL suite
+# instead of skipping tests:
+#   * curl        - hard dependency of the file:// backend tests (parse_output)
+#   * sed         - GNU sed provides `sed -z`, needed by the redaction multiline
+#                   test (busybox sed lacks it)
+#   * util-linux  - provides script(1), needed by the record-mode tests
+#   * python3     - needed by the real-PTY record test (tests/pty_run.py)
+# Everything except curl is best-effort: those tests skip cleanly if their tool
+# is missing. curl, by contrast, is verified below and is a hard failure, since
+# without it the backend tests fail with confusing "produced no output" errors
+# that look like code bugs rather than a missing tool.
 if command -v apk >/dev/null 2>&1; then
-  apk -q add curl 2>/dev/null || true;
+  echo "  Installing test tools via apk (curl, GNU sed, util-linux, python3)...";
+  apk add --no-cache curl sed util-linux python3 || echo "  apk add failed (some tests may skip)";
+fi
+if ! command -v curl >/dev/null 2>&1; then
+  echo "ERROR: curl is required to run the test suite (file:// backend tests) but could not be installed." >&2;
+  echo "       Install curl and re-run, e.g. 'apk add curl' or 'apt-get install curl'." >&2;
+  exit 1;
 fi
 
 echo "Installing ell launcher...";
@@ -44,11 +60,21 @@ echo "Running tests...";
 # so we remember the first failure instead of letting a later passing test
 # mask an earlier regression.
 suite_status=0;
+# Count skipped checks across all tests. A test prints "SKIP: <reason>" for each
+# check it cannot run (a missing tool, not a failure); we tally them so the
+# final summary shows how many were skipped rather than leaving them scattered.
+suite_skipped=0;
+_run_out="$(mktemp 2>/dev/null || echo /tmp/ell_run_out.$$)";
 
 run_test() {
   echo "Running test: ${1}";
-  bash "${1}";
-  status="${?}";
+  # Capture output to tally SKIP lines while still showing it live via tee.
+  bash "${1}" 2>&1 | tee "${_run_out}";
+  status="${PIPESTATUS[0]}";
+  # `grep -c` prints the count but exits 1 when there are no matches; capture the
+  # count and ignore the exit status (a bare number, so arithmetic is safe).
+  skipped="$(grep -c '^SKIP:' "${_run_out}" 2>/dev/null)";
+  suite_skipped=$(( suite_skipped + skipped ));
   if [ "${status}" -ne 0 ]; then
     echo "Test failed: ${1} (exit ${status})";
     suite_status=1;
@@ -80,8 +106,37 @@ if [ -n "${unit_tests}" ]; then
 fi
 
 # --- End-to-end tests (explicit) --------------------------------------------
+# The assertion library's own meta-tests live in tests/ (excluded from unit-test
+# auto-discovery), so register them explicitly.
+run_test tests/assert_lib.test.sh;
 run_test tests/templating.sh;
 run_test tests/parse_output.sh;
+run_test tests/interactive.sh;
+run_test tests/output_redirect.sh;
+run_test tests/record_launcher.sh;
+run_test tests/record_pty.sh;
+run_test tests/error_paths.sh;
+run_test tests/launcher.sh;
+run_test tests/hooks.sh;
+run_test tests/bash_version.sh;
+run_test tests/terminal_size.sh;
+
+rm -f "${_run_out}";
+
+# Suite-wide summary. Skipped checks are informational (a tool was unavailable
+# in this environment, e.g. GNU sed / script / python in a minimal container),
+# not failures.
+echo "";
+if [ "${suite_skipped}" -gt 0 ]; then
+  echo "Suite: ${suite_skipped} check(s) skipped (missing optional tools in this environment).";
+else
+  echo "Suite: no checks skipped (all tools available).";
+fi
+if [ "${suite_status}" -eq 0 ]; then
+  echo "Suite: all tests passed.";
+else
+  echo "Suite: one or more tests FAILED.";
+fi
 
 # Propagate the suite status: fail if any test above failed, so a regression in
 # any test fails CI.
diff --git a/tests/error_paths.sh b/tests/error_paths.sh
new file mode 100644
index 0000000..5988a17
--- /dev/null
+++ b/tests/error_paths.sh
@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+
+# End-to-end tests for ell.sh's fatal error paths.
+#
+# ell.sh has several `logging_fatal; exit 1` branches that were never asserted,
+# so a regression turning a fatal condition into a silent success (or a hang)
+# would go unnoticed. These drive the real ell entrypoint and check both the
+# non-zero exit and the specific error message, so each test fails for the right
+# reason. Every invocation is wrapped in `timeout` so a hang fails loudly.
+
+set -o posix;
+
+DIR="$(cd "$(dirname "${0}")" && pwd)";
+. "${DIR}/assert.sh";
+
+WORK="$(mktemp -d)";
+trap 'rm -rf "${WORK}"' EXIT;
+
+echo "error path tests";
+echo "================";
+
+# --- Template not found -----------------------------------------------------
+# A template name that resolves to nothing must exit non-zero with a clear
+# "Template not found" message, not fall through.
+err="$(printf '' | ell_timeout 8 env TO_TTY=false \
+  "${DIR}/../ell" --api-style ell_echo -t no_such_template_xyz "hi" 2>&1 >/dev/null)";
+status="${?}";
+assert_not_equals "template-not-found exits non-zero" "0" "${status}";
+assert_contains   "template-not-found reports the cause" "${err}" "Template not found";
+
+# --- Input file not found ---------------------------------------------------
+# -f pointing at a missing file must exit non-zero with "Input file not found".
+err="$(ell_timeout 8 env TO_TTY=false ELL_TEMPLATE_PATH="${DIR}/../templates/" \
+  "${DIR}/../ell" --api-style ell_echo -m gpt-4o -t default-openai \
+  -f "${WORK}/missing_input.txt" "hi" 2>&1 >/dev/null)";
+status="${?}";
+assert_not_equals "input-file-not-found exits non-zero" "0" "${status}";
+assert_contains   "input-file-not-found reports the cause" "${err}" "Input file not found";
+
+# --- Empty payload ----------------------------------------------------------
+# An empty template renders an empty payload; ell must refuse rather than send
+# nothing. Point at a template dir containing an empty template file.
+: > "${WORK}/empty.json";
+err="$(printf '' | ell_timeout 8 env TO_TTY=false ELL_TEMPLATE_PATH="${WORK}/" \
+  "${DIR}/../ell" --api-style ell_echo -t empty "hi" 2>&1 >/dev/null)";
+status="${?}";
+assert_not_equals "empty-payload exits non-zero" "0" "${status}";
+assert_contains   "empty-payload reports the cause" "${err}" "Failed to build request payload";
+
+# --- Missing ELL_API_URL preflight ------------------------------------------
+# A network backend with no ELL_API_URL must fail early with a clear, actionable
+# message rather than an opaque curl error later. Run in an isolated env so the
+# developer's own ~/.ellrc / XDG config cannot supply a URL.
+# ell_timeout wraps the whole `env -i ...` invocation (it cannot go after
+# `env -i`, which would try to exec the shell function as a program).
+err="$(ell_timeout 8 env -i PATH="${PATH}" HOME="${WORK}/empty_home" \
+  XDG_CONFIG_HOME="${WORK}/empty_cfg" XDG_DATA_HOME="${WORK}/empty_data" \
+  TO_TTY=false ELL_TEMPLATE_PATH="${DIR}/../templates/" \
+  "${DIR}/../ell" --api-style openai -m gpt-4o "hi" </dev/null 2>&1 >/dev/null)";
+status="${?}";
+assert_not_equals "missing ELL_API_URL exits non-zero" "0" "${status}";
+assert_contains   "missing ELL_API_URL names the variable" "${err}" "ELL_API_URL is not set";
+
+# The ell_echo backend needs no URL, so the preflight must NOT block it.
+echo_status="$(ell_timeout 8 env -i PATH="${PATH}" HOME="${WORK}/empty_home" \
+  XDG_CONFIG_HOME="${WORK}/empty_cfg" XDG_DATA_HOME="${WORK}/empty_data" \
+  TO_TTY=false ELL_TEMPLATE_PATH="${DIR}/../templates/" \
+  "${DIR}/../ell" --api-style ell_echo -m gpt-4o --api-disable-streaming "hi" \
+  </dev/null >/dev/null 2>&1; printf '%s' "${?}")";
+assert_equals "ell_echo is exempt from the URL preflight" "0" "${echo_status}";
+
+assert_summary;
diff --git a/tests/gemini-stream-braces.json b/tests/gemini-stream-braces.json
new file mode 100644
index 0000000..ebf85d7
--- /dev/null
+++ b/tests/gemini-stream-braces.json
@@ -0,0 +1,15 @@
+[{
+  "candidates": [
+    {
+      "content": {
+        "parts": [
+          {
+            "text": "code: if (x) { return \"}\"; } end"
+          }
+        ]
+      },
+      "finishReason": "STOP"
+    }
+  ]
+}
+]
diff --git a/tests/gemini-stream-truncated.json b/tests/gemini-stream-truncated.json
new file mode 100644
index 0000000..decea30
--- /dev/null
+++ b/tests/gemini-stream-truncated.json
@@ -0,0 +1,15 @@
+[{
+  "candidates": [
+    {
+      "content": {
+        "parts": [
+          {
+            "text": "This answer was cut"
+          }
+        ]
+      },
+      "finishReason": "MAX_TOKENS"
+    }
+  ]
+}
+]
diff --git a/tests/hooks.sh b/tests/hooks.sh
new file mode 100644
index 0000000..3986423
--- /dev/null
+++ b/tests/hooks.sh
@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+
+# End-to-end tests for ell.sh's plugin hook integration.
+#
+# ell defines four hook points and applies them at specific stages of the
+# pipeline:
+#   post_input  - transforms USER_PROMPT before it is put into the template
+#   pre_llm     - transforms the request payload before it reaches the backend
+#   post_llm    - transforms the backend's response
+#   pre_output  - transforms the final text before it is written to stdout
+#
+# The individual pieces (piping, hook discovery, the bundled hook scripts) have
+# unit tests, but ell.sh's orchestration -- discovering hooks and applying each
+# at the correct stage -- was only covered indirectly. These tests install a
+# custom plugin with all four hooks, each leaving a distinct marker, and use the
+# ell_echo backend (which echoes the request payload) to prove each hook ran at
+# the right point in the data flow.
+
+set -o posix;
+
+DIR="$(cd "$(dirname "${0}")" && pwd)";
+. "${DIR}/assert.sh";
+
+WORK="$(mktemp -d)";
+trap 'rm -rf "${WORK}"' EXIT;
+
+# Isolated search roots so only our probe plugin (and the bundled ones, which
+# are TTY-gated and pass through under TO_TTY=false) are discovered.
+CFG="${WORK}/cfg";
+PLUGIN="${CFG}/ell/plugins/probe";
+mkdir -p "${PLUGIN}" "${WORK}/data" "${WORK}/home";
+
+# post_input: append _POSTINPUT to the prompt (before templating).
+printf '#!/usr/bin/env bash\nsed '\''s/$/_POSTINPUT/'\''\n' > "${PLUGIN}/10_post_input.sh";
+# pre_llm: prefix the payload's first line (before it reaches the backend).
+printf '#!/usr/bin/env bash\nsed '\''1s/^/PRELLM_/'\''\n' > "${PLUGIN}/10_pre_llm.sh";
+# post_llm: append _POSTLLM to every line of the backend response.
+printf '#!/usr/bin/env bash\nsed '\''s/$/_POSTLLM/'\''\n' > "${PLUGIN}/10_post_llm.sh";
+# pre_output: append _PREOUTPUT to every line of the final output.
+printf '#!/usr/bin/env bash\nsed '\''s/$/_PREOUTPUT/'\''\n' > "${PLUGIN}/10_pre_output.sh";
+chmod +x "${PLUGIN}"/*.sh;
+
+run() {
+  printf '' | env \
+    XDG_CONFIG_HOME="${CFG}" XDG_DATA_HOME="${WORK}/data" HOME="${WORK}/home" \
+    ELL_TEMPLATE_PATH="${DIR}/../templates/" TO_TTY=false \
+    "${DIR}/../ell" --api-style ell_echo -m gpt-4o --api-disable-streaming "HELLO" \
+    2>/dev/null;
+}
+
+echo "hook integration tests";
+echo "======================";
+
+out="$(run)";
+
+# post_input ran before templating: the transformed prompt is embedded in the
+# payload's user content.
+assert_contains "post_input transforms the prompt before templating" \
+  "${out}" "HELLO_POSTINPUT";
+
+# pre_llm ran before the backend: its prefix is on the payload the backend
+# echoed back (the payload starts with the JSON object, so PRELLM_ precedes '{').
+assert_contains "pre_llm transforms the payload before the backend" \
+  "${out}" "PRELLM_{";
+
+# post_llm ran on the backend response, and pre_output ran after post_llm: every
+# line ends with _POSTLLM_PREOUTPUT (post_llm applied first, then pre_output).
+assert_contains "post_llm then pre_output applied in order" \
+  "${out}" "_POSTLLM_PREOUTPUT";
+
+# All four hook markers are present.
+for marker in _POSTINPUT PRELLM_ _POSTLLM _PREOUTPUT; do
+  assert_contains "hook marker ${marker} present" "${out}" "${marker}";
+done
+
+# With no custom plugins installed, output is unaffected by these markers
+# (guards against the markers leaking from somewhere else).
+plain="$(
+  printf '' | env \
+    XDG_CONFIG_HOME="${WORK}/empty" XDG_DATA_HOME="${WORK}/empty" HOME="${WORK}/empty" \
+    ELL_TEMPLATE_PATH="${DIR}/../templates/" TO_TTY=false \
+    "${DIR}/../ell" --api-style ell_echo -m gpt-4o --api-disable-streaming "HELLO" \
+    2>/dev/null;
+)";
+assert_not_contains "no probe markers without the plugin" "${plain}" "_POSTLLM";
+
+assert_summary;
diff --git a/tests/interactive.sh b/tests/interactive.sh
new file mode 100644
index 0000000..95493e2
--- /dev/null
+++ b/tests/interactive.sh
@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+
+# End-to-end tests for interactive mode (ell -i).
+#
+# Interactive mode reads prompts from stdin in a loop. On EOF (Ctrl-D) it must
+# exit cleanly: previously the read had no EOF handling, so at end-of-input the
+# loop spun forever emitting empty completions. Every ell invocation here is
+# wrapped in `timeout` so a regression to that infinite loop fails the test
+# (exit 124) instead of hanging the whole suite.
+#
+# The ell_echo backend echoes the request body ell built, so feeding prompts on
+# stdin lets us confirm each one was processed without any network.
+
+set -o posix;
+
+DIR="$(cd "$(dirname "${0}")" && pwd)";
+. "${DIR}/assert.sh";
+
+# Interactive mode normally auto-enables record mode, which re-executes ell
+# inside `script`; `script`'s own handling of a piped (non-TTY) stdin is a
+# separate matter. What these tests target is the interactive read loop itself
+# (the EOF handling we fixed), which is exactly the code path taken by the inner
+# ell that `script` runs. To reach that loop directly and deterministically --
+# without a pty -- we point ELL_TMP_SHELL_LOG at an existing file so the
+# record-mode entry condition (`[ ! -f "${ELL_TMP_SHELL_LOG}" ]`) is false and
+# ell goes straight into the interactive loop.
+SHELL_LOG="$(mktemp)";
+trap 'rm -f "${SHELL_LOG}"' EXIT;
+
+# run_interactive <stdin-text>: feed text to the interactive read loop (bounded
+# by a timeout) and print the output.
+run_interactive() {
+  printf '%s' "${1}" | ell_timeout 10 \
+    env ELL_TEMPLATE_PATH="${DIR}/../templates/" TO_TTY=false \
+    ELL_TMP_SHELL_LOG="${SHELL_LOG}" \
+    "${DIR}/../ell" --api-style ell_echo -m gpt-4o --api-disable-streaming -i \
+    2>/dev/null;
+}
+
+# run_status <stdin-text>: same as run_interactive but returns the exit status
+# (discarding output). A status of 124 means timeout, i.e. the infinite-loop
+# regression.
+run_status() {
+  printf '%s' "${1}" | ell_timeout 10 \
+    env ELL_TEMPLATE_PATH="${DIR}/../templates/" TO_TTY=false \
+    ELL_TMP_SHELL_LOG="${SHELL_LOG}" \
+    "${DIR}/../ell" --api-style ell_echo -m gpt-4o --api-disable-streaming -i \
+    >/dev/null 2>&1;
+}
+
+echo "interactive tests";
+echo "=================";
+
+# Immediate EOF (empty stdin): must exit cleanly and quickly, not hang.
+run_status "";
+status="${?}";
+assert_equals "immediate EOF exits cleanly (no hang)" "0" "${status}";
+
+# A single prompt then EOF: the prompt is processed, then it exits.
+run_status "$(printf 'hello there\n')";
+status="${?}";
+assert_equals "one prompt then EOF exits 0" "0" "${status}";
+out="$(run_interactive "$(printf 'hello there\n')")";
+assert_contains "single prompt processed" "${out}" "hello there";
+
+# Multiple prompts then EOF: each is processed, then it exits.
+out="$(run_interactive "$(printf 'first prompt\nsecond prompt\n')")";
+assert_contains "first prompt processed"  "${out}" "first prompt";
+assert_contains "second prompt processed" "${out}" "second prompt";
+
+# A prompt with no trailing newline before EOF still exits (does not hang).
+run_status "no newline at end";
+status="${?}";
+assert_equals "unterminated line then EOF exits (no hang)" "0" "${status}";
+
+# The entry hint is an info-level message: quiet at the default log level, but
+# shown at info (>= 4). When shown, it must name the correct exit key -- Ctrl-D,
+# since the loop exits on EOF, not Ctrl-C.
+hint="$(
+  printf '' | ell_timeout 10 \
+    env ELL_TEMPLATE_PATH="${DIR}/../templates/" TO_TTY=false ELL_LOG_LEVEL=4 \
+    ELL_TMP_SHELL_LOG="${SHELL_LOG}" \
+    "${DIR}/../ell" --api-style ell_echo -m gpt-4o --api-disable-streaming -i \
+    2>&1 >/dev/null;
+)";
+assert_contains     "entry hint names Ctrl-D at info level" "${hint}" "Ctrl-D";
+assert_not_contains "entry hint does not say ^C"            "${hint}" "^C";
+
+# It stays quiet at the default log level (info is not shown there).
+hint_default="$(
+  printf '' | ell_timeout 10 \
+    env ELL_TEMPLATE_PATH="${DIR}/../templates/" TO_TTY=false \
+    ELL_TMP_SHELL_LOG="${SHELL_LOG}" \
+    "${DIR}/../ell" --api-style ell_echo -m gpt-4o --api-disable-streaming -i \
+    2>&1 >/dev/null;
+)";
+assert_not_contains "entry hint is quiet at default level" "${hint_default}" "Interactive mode enabled";
+
+assert_summary;
diff --git a/tests/launcher.sh b/tests/launcher.sh
new file mode 100644
index 0000000..288693e
--- /dev/null
+++ b/tests/launcher.sh
@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+
+# End-to-end tests for the `ell` launcher's path resolution.
+#
+# `ell` is a thin wrapper that resolves its own directory (following symlinks)
+# and execs the real `${ELL_DIR}/ell.sh`, so the bundled helpers/templates are
+# always found no matter how ell was invoked. This is the documented install
+# path (symlinking ell into ~/.local/bin), so the symlink resolution must work.
+#
+# These tests invoke the launcher directly, by absolute path, and through
+# symlinks in other directories (both absolute and relative), and confirm each
+# time that the real ell.sh ran (its ell_echo output carries a unique marker).
+
+set -o posix;
+
+DIR="$(cd "$(dirname "${0}")" && pwd)";
+. "${DIR}/assert.sh";
+
+WORK="$(mktemp -d)";
+trap 'rm -rf "${WORK}"' EXIT;
+
+# The symlink cases require real symbolic links. On Windows Git Bash `ln -s`
+# usually degrades to a copy (unless MSYS=winsymlinks:nativestrict and the user
+# can create links), so those cases cannot be exercised there and are SKIPped
+# (see docs/Configuration.md, "Windows"). Probe once: make a link and confirm
+# the OS reports it as a symlink whose target reads back.
+symlinks_supported() {
+  local t="${WORK}/.link_probe" l="${WORK}/.link_probe_ln";
+  printf '' > "${t}";
+  rm -f "${l}";
+  ln -s "${t}" "${l}" 2>/dev/null || { rm -f "${t}" "${l}"; return 1; }
+  if [ -L "${l}" ]; then rm -f "${t}" "${l}"; return 0; fi
+  rm -f "${t}" "${l}";
+  return 1;
+}
+if symlinks_supported; then SYMLINKS_OK=true; else SYMLINKS_OK=false; fi
+
+# run_launcher <path-to-launcher> <marker> [workdir]
+# Invoke the launcher (optionally from <workdir>) against the ell_echo backend
+# and print its output. The marker is the prompt, which ell_echo echoes back in
+# the request body, proving the real ell.sh ran.
+run_launcher() {
+  local launcher="${1}" marker="${2}" workdir="${3:-${DIR}}";
+  (
+    cd "${workdir}" || exit 1;
+    printf '' | ell_timeout 8 env TO_TTY=false ELL_TEMPLATE_PATH="${DIR}/../templates/" \
+      "${launcher}" --api-style ell_echo -m gpt-4o --api-disable-streaming "${marker}" \
+      2>/dev/null;
+  );
+}
+
+echo "launcher tests";
+echo "==============";
+
+# Direct absolute path.
+out="$(run_launcher "$(cd "${DIR}/.." && pwd)/ell" MARK_ABS)";
+assert_contains "launcher runs via absolute path" "${out}" "MARK_ABS";
+
+if [ "${SYMLINKS_OK}" = "true" ]; then
+  # Symlink in another directory pointing at the launcher (absolute target).
+  ln -s "$(cd "${DIR}/.." && pwd)/ell" "${WORK}/ell_abs_link";
+  out="$(run_launcher "${WORK}/ell_abs_link" MARK_SYMLINK)";
+  assert_contains "launcher runs via absolute symlink" "${out}" "MARK_SYMLINK";
+
+  # Relative symlink invoked from its own directory (exercises the relative
+  # link-target resolution in the launcher).
+  (
+    cd "${WORK}" || exit 1;
+    ln -s "ell_abs_link" "ell_rel_link";
+  );
+  out="$(run_launcher "./ell_rel_link" MARK_REL "${WORK}")";
+  assert_contains "launcher runs via relative symlink" "${out}" "MARK_REL";
+
+  # A chain of symlinks resolves to the real ell.sh.
+  ln -s "${WORK}/ell_rel_link" "${WORK}/ell_chain";
+  out="$(run_launcher "${WORK}/ell_chain" MARK_CHAIN)";
+  assert_contains "launcher runs via a symlink chain" "${out}" "MARK_CHAIN";
+else
+  echo "SKIP: launcher runs via absolute symlink (real symlinks unsupported here)";
+  echo "SKIP: launcher runs via relative symlink (real symlinks unsupported here)";
+  echo "SKIP: launcher runs via a symlink chain (real symlinks unsupported here)";
+fi
+
+assert_summary;
diff --git a/tests/openai-stream-truncated.json b/tests/openai-stream-truncated.json
new file mode 100644
index 0000000..1c718bb
--- /dev/null
+++ b/tests/openai-stream-truncated.json
@@ -0,0 +1,8 @@
+data: {"id":"chatcmpl-trunc","object":"chat.completion.chunk","created":1723855353,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]}
+
+data: {"id":"chatcmpl-trunc","object":"chat.completion.chunk","created":1723855353,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{"content":"This answer was cut"},"logprobs":null,"finish_reason":null}]}
+
+data: {"id":"chatcmpl-trunc","object":"chat.completion.chunk","created":1723855353,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"length"}]}
+
+data: [DONE]
+
diff --git a/tests/output_redirect.sh b/tests/output_redirect.sh
new file mode 100644
index 0000000..7ed6be5
--- /dev/null
+++ b/tests/output_redirect.sh
@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+
+# End-to-end tests for stdout-to-file redirection (-o / --output-file).
+#
+# ell redirects stdout to ELL_OUTPUT_FILE only in plain (non-record,
+# non-interactive) mode. The guard used to compare `"${ELL_RECORD}" != "xtrue"`
+# with the 'x' prefix on only one side, so it was always true and the redirect
+# fired even in record/interactive mode. These tests pin the correct behaviour:
+#   * plain mode + -o FILE  -> completion goes to FILE, terminal stdout is empty
+#   * plain mode, no -o     -> completion goes to stdout
+#   * interactive mode + -o -> stdout is NOT hijacked by the -o redirect
+#
+# The ell_echo backend echoes the request body, so we can see where output went.
+
+set -o posix;
+
+DIR="$(cd "$(dirname "${0}")" && pwd)";
+. "${DIR}/assert.sh";
+
+WORK="$(mktemp -d)";
+trap 'rm -rf "${WORK}"' EXIT;
+
+COMMON_ENV=(ELL_TEMPLATE_PATH="${DIR}/../templates/" TO_TTY=false);
+
+echo "output redirect tests";
+echo "=====================";
+
+# --- Plain mode + -o FILE: output goes to the file, not to stdout -----------
+out_file="${WORK}/out.json";
+stdout="$(printf '' | env "${COMMON_ENV[@]}" \
+  "${DIR}/../ell" --api-style ell_echo -m gpt-4o --api-disable-streaming \
+  -o "${out_file}" UNIQUE_REDIRECT_XYZ 2>/dev/null)";
+assert_equals   "plain mode -o leaves stdout empty" "" "${stdout}";
+file_contents="$(cat "${out_file}" 2>/dev/null)";
+assert_contains "plain mode -o writes completion to the file" "${file_contents}" "UNIQUE_REDIRECT_XYZ";
+
+# --- Plain mode, no -o: output goes to stdout -------------------------------
+stdout="$(printf '' | env "${COMMON_ENV[@]}" \
+  "${DIR}/../ell" --api-style ell_echo -m gpt-4o --api-disable-streaming \
+  UNIQUE_STDOUT_XYZ 2>/dev/null)";
+assert_contains "no -o writes completion to stdout" "${stdout}" "UNIQUE_STDOUT_XYZ";
+
+# --- Interactive mode + -o: stdout is NOT hijacked by the -o redirect -------
+# Point ELL_TMP_SHELL_LOG at an existing file so record-mode re-entry is skipped
+# and ell goes straight into the interactive loop (the path the inner ell runs
+# under `script`). With the bug, the -o file redirect fired even here; with the
+# fix, the interactive completion is still emitted on stdout. Bounded by timeout
+# so an EOF-loop regression cannot hang the suite.
+shell_log="${WORK}/shelllog";
+: > "${shell_log}";
+redirect_file="${WORK}/should_stay_empty.json";
+stdout="$(printf 'INTERACTIVE_XYZ\n' | ell_timeout 10 env "${COMMON_ENV[@]}" \
+  ELL_TMP_SHELL_LOG="${shell_log}" \
+  "${DIR}/../ell" --api-style ell_echo -m gpt-4o --api-disable-streaming \
+  -o "${redirect_file}" -i 2>/dev/null)";
+assert_contains "interactive completion still reaches stdout" "${stdout}" "INTERACTIVE_XYZ";
+
+assert_summary;
diff --git a/tests/parse_output.sh b/tests/parse_output.sh
index 4b765fe..625c7c1 100644
--- a/tests/parse_output.sh
+++ b/tests/parse_output.sh
@@ -32,6 +32,22 @@ run_ell() {
     "${DIR}/../ell" test 2>/dev/null;
 }
 
+# run_ell_fixture_status <style> <stream> <fixture-basename>
+# Runs `ell test` against an explicit fixture file and returns ell's exit
+# status (output discarded). Used to assert that abnormal responses fail.
+run_ell_fixture_status() {
+  local style="${1}" stream="${2}" fixture="${3}";
+  ELL_API_STYLE="${style}" \
+  ELL_LLM_MODEL="model" \
+  ELL_API_STREAM="${stream}" \
+  ELL_API_URL="file://${DIR}/${fixture}#" \
+  ELL_API_KEY="" \
+  ELL_TEMPLATE_PATH="${DIR}/../templates/" \
+  ELL_TEMPLATE="default-${style}" \
+  TO_TTY=false \
+    "${DIR}/../ell" test >/dev/null 2>&1;
+}
+
 echo "parse_output tests";
 echo "==================";
 
@@ -48,6 +64,17 @@ assert_not_equals "openai stream produced output" "" "${out}";
 assert_contains   "openai stream parsed content"  "${out}" "Markdown";
 assert_not_contains "openai stream leaks no data: prefix" "${out}" 'data:';
 
+# A well-formed streaming completion (finish_reason "stop") exits 0.
+assert_success "openai stream stop exits 0" \
+  run_ell_fixture_status openai true "openai-stream.json";
+
+# A truncated streaming completion (choices.0.finish_reason "length") must be
+# reported as a failure, not silently succeed. This is the regression guard for
+# the finish-reason path bug: the check previously looked at a root-level
+# "finish_reason" that never existed, so truncation went undetected.
+assert_failure "openai stream truncation is detected" \
+  run_ell_fixture_status openai true "openai-stream-truncated.json";
+
 # --- Gemini ------------------------------------------------------------------
 
 out="$(run_ell gemini gemini-1.5-flash false)";
@@ -60,4 +87,26 @@ assert_not_equals "gemini stream produced output" "" "${out}";
 assert_contains   "gemini stream parsed content"  "${out}" "Comprehensive Markdown Guide";
 assert_not_contains "gemini stream leaks no parts key" "${out}" '"parts"';
 
+# A well-formed gemini stream (finishReason "STOP") exits 0; a truncated one
+# (e.g. MAX_TOKENS) is reported as a failure. This mirrors the openai guard and
+# closes the previous openai/gemini asymmetry (there was no gemini truncated
+# fixture).
+assert_success "gemini stream stop exits 0" \
+  run_ell_fixture_status gemini true "gemini-stream.json";
+assert_failure "gemini stream truncation is detected" \
+  run_ell_fixture_status gemini true "gemini-stream-truncated.json";
+
+# The gemini streaming reader tracks JSON object boundaries by brace depth. A
+# text value containing braces, quotes and escaped quotes must not confuse that
+# tracking: the whole value must round-trip intact. This guards the object-
+# boundary parser that replaced the O(n^2) re-parse-the-whole-buffer approach.
+out="$(
+  ELL_API_STYLE=gemini ELL_LLM_MODEL=m ELL_API_STREAM=true \
+  ELL_API_URL="file://${DIR}/gemini-stream-braces.json#" ELL_API_KEY="" \
+  ELL_TEMPLATE_PATH="${DIR}/../templates/" ELL_TEMPLATE=default-gemini \
+  TO_TTY=false "${DIR}/../ell" test 2>/dev/null;
+)";
+assert_contains "gemini handles braces/quotes inside a string value" \
+  "${out}" 'if (x) { return "}"; } end';
+
 assert_summary;
diff --git a/tests/pty_run.py b/tests/pty_run.py
new file mode 100755
index 0000000..dd545be
--- /dev/null
+++ b/tests/pty_run.py
@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Run a command inside a real pseudo-terminal, feeding scripted input.
+
+Some ell behaviour (record mode, interactive prompts) only exercises its real
+code path over a tty, which a pipe cannot emulate. This helper gives a command
+a genuine PTY so shell tests can drive it. It is intentionally generic and not
+record-specific.
+
+Usage:
+    pty_run.py [--timeout SECONDS] [--send-eof] \\
+               [--input LINE] [--delay SECONDS] -- CMD [ARG...]
+
+Options:
+    --input LINE     A line to type into the PTY (the trailing newline is
+                     added). May be given multiple times, sent in order.
+    --send-eof       Send Ctrl-D (EOF) after the inputs.
+    --delay SECONDS  Pause before/after sending inputs (default 1.0), to let
+                     the child reach its prompt.
+    --timeout SECONDS Overall bound (default 15); on expiry the child is
+                     killed and exit status 124 is reported (like `timeout`).
+
+The child's stdout/stderr (as seen on the PTY) is streamed to this process's
+stdout. The final line printed is always:
+    CHILD_EXIT=<n>
+where <n> is the child's exit status, or 124 on timeout, or -1 if it could not
+be determined. Tests should parse that line.
+"""
+
+import argparse
+import os
+import pty
+import select
+import sys
+import time
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("--timeout", type=float, default=15.0)
+    parser.add_argument("--delay", type=float, default=1.0)
+    parser.add_argument("--input", action="append", default=[])
+    parser.add_argument("--send-eof", action="store_true")
+    parser.add_argument("command", nargs=argparse.REMAINDER)
+    args = parser.parse_args()
+
+    cmd = args.command
+    if cmd and cmd[0] == "--":
+        cmd = cmd[1:]
+    if not cmd:
+        sys.stderr.write("pty_run.py: no command given\n")
+        return 2
+
+    pid, fd = pty.fork()
+    if pid == 0:
+        # Child: become the command inside the PTY.
+        os.execvp(cmd[0], cmd)
+        os._exit(127)  # execvp only returns on failure
+
+    # Parent: let the child reach its prompt, send the scripted input, then EOF.
+    time.sleep(args.delay)
+    for line in args.input:
+        os.write(fd, (line + "\n").encode())
+        time.sleep(args.delay)
+    if args.send_eof:
+        os.write(fd, b"\x04")  # Ctrl-D
+
+    deadline = time.time() + args.timeout
+    timed_out = False
+    while True:
+        if time.time() >= deadline:
+            timed_out = True
+            break
+        try:
+            r, _, _ = select.select([fd], [], [], 0.5)
+        except OSError:
+            break
+        if not r:
+            continue
+        try:
+            chunk = os.read(fd, 4096)
+        except OSError:
+            break
+        if not chunk:
+            break
+        sys.stdout.buffer.write(chunk)
+        sys.stdout.buffer.flush()
+
+    if timed_out:
+        try:
+            import signal
+
+            os.kill(pid, signal.SIGKILL)
+        except OSError:
+            pass
+        try:
+            os.waitpid(pid, 0)
+        except OSError:
+            pass
+        print("CHILD_EXIT=124")
+        return 0
+
+    try:
+        _, status = os.waitpid(pid, 0)
+        code = os.WEXITSTATUS(status) if os.WIFEXITED(status) else -1
+    except OSError:
+        code = -1
+    print("CHILD_EXIT=%d" % code)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/tests/record_launcher.sh b/tests/record_launcher.sh
new file mode 100644
index 0000000..e704c9a
--- /dev/null
+++ b/tests/record_launcher.sh
@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+
+# End-to-end test for record mode locating ell correctly.
+#
+# Record mode re-execs ell inside `script -c "<cmd>"`. That command used to be a
+# bare `ell`, which only works when ell is installed on PATH; running in place
+# (./ell.sh) or from an uninstalled checkout failed with "ell: command not
+# found". The fix re-execs "${BASE_DIR}/ell" as an absolute, shell-quoted path.
+#
+# This test drives record+interactive mode from a checkout that is NOT on PATH
+# and whose directory contains a space (to also exercise the quoting), and
+# asserts the inner ell actually ran (its echoed payload appears) and that no
+# "command not found" occurred. It does not assert a clean exit: record mode
+# wraps `script`, whose handling of a piped (non-TTY) stdin is a separate issue,
+# so the whole thing is bounded by `timeout`.
+
+set -o posix;
+
+DIR="$(cd "$(dirname "${0}")" && pwd)";
+. "${DIR}/assert.sh";
+
+REPO_DIR="$(cd "${DIR}/.." && pwd)";
+
+if ! command -v script >/dev/null 2>&1; then
+  echo "SKIP: record_launcher (script(1) not available)";
+  assert_summary;
+  return 0 2>/dev/null || exit 0;
+fi
+
+echo "record launcher tests";
+echo "=====================";
+
+# Copy the checkout into a path containing a space so the launcher path must be
+# quoted, and run it without adding it to PATH.
+WORK="$(mktemp -d)";
+trap 'rm -rf "${WORK}"' EXIT;
+SPACED="${WORK}/dir with space";
+mkdir -p "${SPACED}";
+cp -r "${REPO_DIR}/." "${SPACED}/repo" 2>/dev/null;
+
+out_file="${WORK}/rec.out";
+err_file="${WORK}/rec.err";
+
+# Build a PATH that has the tools record mode needs but definitely NOT `ell`, so
+# the test proves record works without ell on PATH. Rather than guess which
+# system directories hold the tools (and risk also exposing an installed ell,
+# e.g. both bash and ell in /usr/local/bin), symlink exactly the tools we need
+# into a dedicated bin dir and use only that. Any tool that cannot be resolved
+# means we cannot isolate; skip cleanly.
+SAFE_BIN="${WORK}/safebin";
+mkdir -p "${SAFE_BIN}";
+_missing_tool="";
+for t in bash script env mktemp dirname chmod cat rm cp tail head grep awk sed printf date stty tr cut; do
+  tp="$(command -v "${t}" 2>/dev/null)";
+  if [ -n "${tp}" ]; then
+    # Best-effort: symlink the tool into the isolated bin. `ln -s` can fail on
+    # platforms without real symlinks (e.g. MSYS2), so fall back to a copy and
+    # silence the error; the runnability probe below is the real gate.
+    ln -sf "${tp}" "${SAFE_BIN}/${t}" 2>/dev/null \
+      || cp -f "${tp}" "${SAFE_BIN}/${t}" 2>/dev/null || :;
+  fi
+done
+SAFE_PATH="${SAFE_BIN}";
+# bash and script are mandatory for record mode; if either is missing we already
+# skipped above (script) or cannot proceed.
+if [ ! -e "${SAFE_BIN}/bash" ]; then
+  echo "SKIP: record_launcher (bash not resolvable for isolated PATH)";
+  assert_summary;
+  return 0 2>/dev/null || exit 0;
+fi
+# The isolated PATH must actually be able to run bash. On some platforms a
+# copied/symlinked bash cannot start (e.g. MSYS2, where bash.exe needs
+# msys-2.0.dll resolved relative to its original location: "cannot open shared
+# object file"). In that case this isolation technique is not viable, so SKIP
+# rather than report a false failure.
+if ! PATH="${SAFE_PATH}" bash -c 'exit 0' >/dev/null 2>&1; then
+  echo "SKIP: record_launcher (isolated bash not runnable in this environment)";
+  assert_summary;
+  return 0 2>/dev/null || exit 0;
+fi
+if PATH="${SAFE_PATH}" command -v ell >/dev/null 2>&1; then
+  echo "SKIP: an 'ell' is reachable even on a minimal PATH; cannot isolate";
+  assert_summary;
+  return 0 2>/dev/null || exit 0;
+fi
+
+# Feed one prompt then EOF; bound with timeout so the known script+pipe EOF
+# behaviour cannot hang the suite. Run with the ell-free PATH.
+(
+  cd "${SPACED}/repo" || exit 1;
+  printf 'RECORD_LAUNCH_XYZ\n' | ell_timeout 12 \
+    env PATH="${SAFE_PATH}" ELL_TEMPLATE_PATH="${SPACED}/repo/templates/" \
+    ./ell.sh --api-style ell_echo -m gpt-4o --api-disable-streaming -r -i \
+    >"${out_file}" 2>"${err_file}";
+);
+
+combined="$(cat "${out_file}" "${err_file}" 2>/dev/null)";
+
+# The inner ell must have been located and run: its echoed request payload
+# contains the prompt. If record had exec'd a bare `ell` not on PATH, we would
+# instead see a "command not found" and no payload.
+assert_contains "record mode located and ran the inner ell" "${combined}" "RECORD_LAUNCH_XYZ";
+# The launcher itself must resolve. Check specifically that the ell launcher
+# path was not reported as not-found, rather than matching a bare "not found"
+# (which could also come from an unrelated optional tool like stty on a minimal
+# PATH and is not what this test is about).
+assert_not_contains "record mode resolved the ell launcher" "${combined}" "ell: No such file";
+assert_not_contains "record mode did not hit ell command-not-found" "${combined}" "ell: command not found";
+
+assert_summary;
diff --git a/tests/record_pty.sh b/tests/record_pty.sh
new file mode 100644
index 0000000..d50e89d
--- /dev/null
+++ b/tests/record_pty.sh
@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+
+# End-to-end test for record mode over a real PTY -- the actual user scenario.
+#
+# `ell -r -i` re-execs itself under `script(1)`, which allocates a pseudo
+# terminal and records the whole session to a log. The other record tests feed
+# a pipe (not a tty) and only check that the inner ell is located; they
+# deliberately avoid a PTY. This test drives ell through a genuine PTY using the
+# tests/pty_run.py helper (python3's pty module -- no extra system dependency,
+# and present on the CI ubuntu/macOS runners) and asserts the real behaviour:
+# the interactive session runs, exits cleanly on EOF, and the prompt is captured
+# in the record log.
+#
+# It skips where the pieces are unavailable (no script(1), or no python3), e.g.
+# the minimal alpine bash containers, which cannot run record mode at all.
+
+set -o posix;
+
+DIR="$(cd "$(dirname "${0}")" && pwd)";
+. "${DIR}/assert.sh";
+
+echo "record PTY tests";
+echo "================";
+
+if ! command -v script >/dev/null 2>&1; then
+  echo "SKIP: record_pty (script(1) not available)";
+  assert_summary;
+  return 0 2>/dev/null || exit 0;
+fi
+PY="";
+for c in python3 python; do
+  command -v "${c}" >/dev/null 2>&1 && { PY="${c}"; break; }
+done
+if [ -z "${PY}" ]; then
+  echo "SKIP: record_pty (python not available for PTY)";
+  assert_summary;
+  return 0 2>/dev/null || exit 0;
+fi
+
+WORK="$(mktemp -d)";
+trap 'rm -rf "${WORK}"' EXIT;
+LOG="${WORK}/session.log";
+
+# Drive `ell -r -i` inside a real PTY via pty_run.py: type one prompt, then
+# Ctrl-D. ELL_OUTPUT_FILE doubles as the record log so we can inspect it. The
+# helper prints "CHILD_EXIT=<n>" as its last line; pty_run.py enforces its own
+# timeout, so no ell_timeout wrapper is needed.
+out="$(
+  cd "${DIR}/.." || exit 1;
+  TO_TTY=false ELL_TEMPLATE_PATH="${DIR}/../templates/" ELL_OUTPUT_FILE="${LOG}" \
+    "${PY}" "${DIR}/pty_run.py" --timeout 15 --input "PTY_RECORD_XYZ" --send-eof -- \
+    ./ell --api-style ell_echo -m gpt-4o --api-disable-streaming -r -i 2>&1;
+)";
+
+# The child (the record session) exited cleanly on EOF.
+assert_contains "record PTY session exits cleanly" "${out}" "CHILD_EXIT=0";
+
+# The session was recorded to the log, including the typed prompt.
+if [ -s "${LOG}" ]; then
+  _assert_pass "record log is non-empty";
+else
+  _assert_fail "record log is non-empty";
+fi
+assert_contains "record log captured the prompt" "$(cat "${LOG}" 2>/dev/null)" "PTY_RECORD_XYZ";
+
+assert_summary;
diff --git a/tests/terminal_size.sh b/tests/terminal_size.sh
new file mode 100644
index 0000000..5ceae91
--- /dev/null
+++ b/tests/terminal_size.sh
@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+
+# Tests for ell.sh's terminal-size handling (PAGE_SIZE / COLUMNS).
+#
+# ell reads the terminal size from `stty size`. When ell runs without a
+# controlling terminal -- the common case when its output is piped to a file or
+# another program -- `stty size` fails/returns nothing, and ell must fall back
+# to sane defaults (PAGE_SIZE=24, COLUMNS=80) rather than leaving them empty
+# (which would break the paginator's arithmetic). PAGE_SIZE and COLUMNS are
+# exported, so a pre_output hook can observe the values ell computed.
+
+set -o posix;
+
+DIR="$(cd "$(dirname "${0}")" && pwd)";
+. "${DIR}/assert.sh";
+
+WORK="$(mktemp -d)";
+trap 'rm -rf "${WORK}"' EXIT;
+
+# A pre_output hook that appends the PAGE_SIZE / COLUMNS ell exported, so we can
+# assert on the values from outside.
+CFG="${WORK}/cfg";
+mkdir -p "${CFG}/ell/plugins/probe" "${WORK}/data" "${WORK}/home";
+{
+  printf '#!/usr/bin/env bash\n';
+  printf 'cat\n';
+  printf 'printf "\\nELL_PAGE_SIZE=%%s ELL_COLUMNS=%%s\\n" "${PAGE_SIZE}" "${COLUMNS}"\n';
+} > "${CFG}/ell/plugins/probe/10_pre_output.sh";
+chmod +x "${CFG}/ell/plugins/probe/10_pre_output.sh";
+
+echo "terminal size tests";
+echo "===================";
+
+# Run with no controlling terminal for stdout (piped), so `stty size` fails.
+out="$(
+  printf '' | env \
+    XDG_CONFIG_HOME="${CFG}" XDG_DATA_HOME="${WORK}/data" HOME="${WORK}/home" \
+    ELL_TEMPLATE_PATH="${DIR}/../templates/" TO_TTY=false \
+    "${DIR}/../ell" --api-style ell_echo -m gpt-4o --api-disable-streaming "hi" \
+    2>/dev/null;
+)";
+
+# Fallbacks must be applied (not empty) when stty size is unavailable.
+assert_contains "PAGE_SIZE falls back to 24 without a tty" "${out}" "ELL_PAGE_SIZE=24";
+assert_contains "COLUMNS falls back to 80 without a tty"    "${out}" "ELL_COLUMNS=80";
+assert_not_contains "PAGE_SIZE is never empty"             "${out}" "ELL_PAGE_SIZE= ";
+
+# The run itself must still succeed despite stty failing.
+status="$(
+  printf '' | env \
+    XDG_CONFIG_HOME="${CFG}" XDG_DATA_HOME="${WORK}/data" HOME="${WORK}/home" \
+    ELL_TEMPLATE_PATH="${DIR}/../templates/" TO_TTY=false \
+    "${DIR}/../ell" --api-style ell_echo -m gpt-4o --api-disable-streaming "hi" \
+    >/dev/null 2>&1; printf '%s' "${?}";
+)";
+assert_equals "ell succeeds without a tty (stty failure tolerated)" "0" "${status}";
+
+assert_summary;