hx-cli 0.2.1__tar.gz → 0.2.3__tar.gz

{hx_cli-0.2.1 → hx_cli-0.2.3}/CHANGELOG.md

@@ -28,6 +28,79 @@ the project follows [semantic versioning](https://semver.org/).
 
 ---
 
+## [0.2.3] - 2026-09-18
+
+### Added
+
+- Hooks: shell commands HX runs at `PreToolUse`, `PostToolUse`,
+  `UserPromptSubmit` and `Stop`. A hook can refuse an action (exit 2, or
+  `{"decision": "block"}`), rewrite a tool's arguments before the permission
+  engine sees them (`updatedInput`), or add a note for the model
+  (`additionalContext`). Configure them under `"hooks"` in
+  `~/.hx/settings.json`; `/hooks` lists what is loaded. Hooks declared in a
+  project's checked-in `.hx/settings.json` are ignored and reported, because
+  cloning a repository must not be enough to run commands on your machine.
+- `Symbols`: outline a file, find where a name is defined, or find where it is
+  used, over a tree-sitter parse tree rather than a regex - so a match inside a
+  comment or a string never counts. Python, TypeScript, JavaScript, Go and
+  Rust. Needs the grammars: `uv tool install "hx-cli[symbols]"`. Without them
+  the tool is not registered at all.
+- An example hook, `examples/hooks/check.sh`: after every `Edit`/`Write` it
+  runs the project's own checker (`ruff`, `tsc`, `go vet`, `cargo check`)
+  against just that file and hands the output back to the model, so a typo is
+  caught on the next turn instead of at test time.
+- Line anchors. `Read` now labels each line with a short content hash, and
+  `Edit` accepts those anchors in a `hashline` argument to replace a span
+  without retyping it. An anchor that no longer resolves means the file moved,
+  so the patch is rejected instead of landing at the wrong lines. Set
+  `"tools": {"hashline": false}` to go back to plain `cat -n` reads.
+
+### Removed
+
+- The `telemetry` setting, which was parsed and never read by anything.
+
+### Fixed
+
+- The README's Status section said there were two model routes; Devin made it
+  three in 0.2.2.
+- `MultiEdit` and `NotebookEdit` were listed as mutating tools and as edit
+  tools in the permission engine, but no such tools exist. A rule written
+  against either name silently matched nothing.
+
+---
+
+## [0.2.2] - 2026-09-17
+
+### Added
+
+- Devin subscription as a third route: `hx auth login devin` (or `/login`)
+  signs in through the browser, and `devin/<model>` ids run against the plan -
+  every model the account includes, listed by `/model` and refreshed with
+  `/models refresh`. Reasoning depths Devin ships as separate models are folded
+  into one, so `/effort` picks the depth, and router models such as
+  `devin/adaptive` are assigned per turn. A session token in `DEVIN_API_KEY`
+  works where there is no browser. Devin Enterprise accounts sign in through
+  the same command by choosing "Log in with Devin for Enterprise".
+
+### Fixed
+
+- The `/login` dialog no longer sits on "Starting…" for the whole sign-in: it
+  now updates as the flow moves on, and keeps the instructions on screen
+  alongside the link, progress and paste field instead of overwriting them.
+
+- Resizing the terminal no longer crashes the session. A window manager sends
+  a burst of SIGWINCH for one drag of a corner, and a signal landing while the
+  previous frame was still writing re-entered stdout: `RuntimeError: reentrant
+  call inside <_io.BufferedWriter>`, and HX was gone. The redraw is handed to
+  the event loop now, and the burst collapses into one repaint.
+
+- `/resume` and `hx resume` bring the whole conversation back, not only its
+  text: the reasoning, tool calls, their output and the plan are drawn again.
+  A resumed session used to show a blank tinted bar for each tool result and
+  nothing at all for the calls themselves.
+
+---
+
 ## [0.2.1] - 2026-09-14
 
 ### Changed
@@ -408,7 +481,9 @@ First release, published to PyPI as [`hx-cli`](https://pypi.org/project/hx-cli/)
 - `/configure` and `hx auth` for the OpenRouter key, `hx upgrade` for
   self-update, and `install.sh` bootstrapping uv with a pinned Python.
 
-[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.1...HEAD
+[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.3...HEAD
+[0.2.3]: https://github.com/aletisunil/hx/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/aletisunil/hx/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/aletisunil/hx/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/aletisunil/hx/compare/v0.1.9...v0.2.0
 [0.1.9]: https://github.com/aletisunil/hx/compare/v0.1.8...v0.1.9

{hx_cli-0.2.1 → hx_cli-0.2.3}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: hx-cli
-Version: 0.2.1
-Summary: HX - a terminal coding agent
+Version: 0.2.3
+Summary: HX - an agent harness for the terminal
 Project-URL: Homepage, https://github.com/aletisunil/hx
 Project-URL: Issues, https://github.com/aletisunil/hx/issues
 Author: Sunil Aleti
@@ -14,7 +14,6 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.11
-Requires-Dist: click>=8.1
 Requires-Dist: httpx>=0.27
 Requires-Dist: markdown-it-py>=3.0
 Requires-Dist: pydantic>=2.7
@@ -31,12 +30,15 @@ Requires-Dist: pytest>=8.2; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
 Requires-Dist: types-pygments; extra == 'dev'
 Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: symbols
+Requires-Dist: tree-sitter-language-pack>=0.7; extra == 'symbols'
+Requires-Dist: tree-sitter>=0.23; extra == 'symbols'
 Description-Content-Type: text/markdown
 
 # HX
 
-A terminal coding agent. Python core, its own terminal renderer, OpenRouter for
-models.
+An agent harness for the terminal. Python core, its own terminal renderer,
+OpenRouter for models.
 
 HX runs in your project directory, reads and edits your code, runs commands in
 a sandboxed shell, and shows you what every turn costs.
@@ -85,13 +87,14 @@ Requires Python 3.11+. macOS and Linux. Update with `hx upgrade`.
 
 ### Credentials
 
-HX reaches models over two routes. Which one serves a turn is decided by the
+HX reaches models over three routes. Which one serves a turn is decided by the
 model id alone, so "what paid for that" is always answerable by reading it:
 
 | Model id | Route | Billing |
 |---|---|---|
 | `anthropic/claude-sonnet-4.5`, `openai/gpt-5`, … | OpenRouter | per token, API key |
 | `openai-codex/gpt-5.6-terra` | ChatGPT Plus/Pro | your subscription |
+| `devin/swe-1-6`, `devin/claude-opus-5`, … | Devin | your subscription |
 
 Credentials live in `~/.hx/auth.json`, mode 0600, one entry per route.
 
@@ -185,6 +188,38 @@ They join the `/model` picker on the next start. HX cannot ask how large an
 unknown model's context window is, so it assumes a conservative 200k — that
 costs an accurate context gauge, not the use of the model.
 
+**Devin.** Sign in with the same browser flow the official `devin` CLI uses,
+and run every model your Devin plan includes - SWE-1.6, and whatever frontier
+models the plan offers - against the subscription:
+
+```sh
+hx auth login devin             # or /login inside the TUI
+hx --model devin/swe-1-6
+hx auth logout devin
+```
+
+**Devin Enterprise** signs in the same way: on the page that opens, choose
+"Log in with Devin for Enterprise", enter your company, and finish through its
+identity provider. Your admin has to grant the "Use Devin CLI" permission first.
+Usage counts toward the organization's allocation, and an enterprise tenant
+served from its own API server is followed there for both turns and the model
+list.
+
+The browser opens to `app.devin.ai` and redirects to a loopback listener on
+`127.0.0.1:59653`. Over SSH, paste the final redirect URL into the prompt
+instead. A Devin login does not refresh: when it expires, HX says so and asks
+you to sign in again. On a machine with no browser at all, a session token in
+`HX_DEVIN_API_KEY` or `DEVIN_API_KEY` is used when nothing is saved.
+
+Signing in fetches the account's own model list, and `/model` offers exactly
+that; `/models refresh` asks again. Devin publishes each reasoning depth as a
+model of its own - Claude Opus 5 High, Claude Opus 5 Max - and HX folds each
+family into one model, so `/effort` picks the depth on Devin exactly as it does
+on Codex. A fast lane or a 1M-context lane stays a separate model, since it
+changes what a turn costs or how much fits. Router models such as
+`devin/adaptive` are resolved to a concrete model on every turn by Devin itself.
+If the list cannot be fetched, `devin/swe-1-6` and `devin/swe-1-6-fast` stand in.
+
 **Web search.** Optional, and the one credential that is not a model route.
 It powers two tools:
 
@@ -270,7 +305,7 @@ hx --system-prompt @p.md    # replace the system prompt for one run
 hx --append-system-prompt "Always run the tests"   # add to it; repeatable
 hx mcp list|add|remove      # manage MCP servers
 hx auth [set|clear]         # manage the OpenRouter key
-hx auth login [provider]    # sign in (openrouter, openai-codex)
+hx auth login [provider]    # sign in (openrouter, openai-codex, devin)
 hx auth logout <provider>   # forget a stored credential
 hx docs [section]           # the manual; no argument lists its sections
 hx changelog [version]      # what shipped in each version
@@ -405,6 +440,7 @@ than being silently resolved.
 | `/skills` | installed skills |
 | `/agents` | subagent types |
 | `/mcp` | server status |
+| `/hooks` | configured hooks, and any that were refused |
 | `/theme [name]` | `dark`, `light`, `ansi`, or any theme in `~/.hx/themes` |
 | `/queue [steer <n>\|clear]` | messages waiting for the turn to end, and what to do with them |
 | `/copy` | copy the last reply to the clipboard |
@@ -522,7 +558,6 @@ along with the `.hx/.gitignore` it added to hide it.
 {
   "theme": "dark",                    // dark | light | ansi, or a file in ~/.hx/themes
   "quiet_startup": false,             // skip the startup header
-  "telemetry": false,
 
   "models": {
     "model": "anthropic/claude-sonnet-4.5",
@@ -565,10 +600,18 @@ along with the `.hx/.gitignore` it added to hide it.
   "tui": {
     "enterWhileBusy": "queue",        // queue | steer - what enter does mid-turn
     "fullscreen": false               // true takes the whole window (see /fullscreen)
+  },
+
+  "tools": {
+    "hashline": true                  // Read labels lines with content anchors Edit accepts
   }
 }
 ```
 
+`hooks` is configured in the same files but is deliberately not part of this
+merge: it is read per layer, and only from your own settings. See
+[Extending it](#extending-it).
+
 Environment overrides: `HX_MODEL`, `HX_SUBAGENT_MODEL`, `HX_MAX_TOKENS`,
 `HX_PERMISSION_MODE`, `HX_SANDBOX`, `HX_COMPACT_AT`, `HX_GIT_NOTICES`,
 `HX_THEME`, `HX_QUIET_STARTUP`. Also `HX_HOME` to relocate user state, `HX_TAVILY_API_KEY`
@@ -729,6 +772,54 @@ rest to the session directory, and hands the model that path to grep.
 
 ---
 
+## Reading and editing code
+
+**Line anchors.** `Read` labels every line with a short content hash:
+
+```
+     1 a3f9	def handle(request):
+     2 7c1c	    if request.method == "POST":
+```
+
+The anchor is a hash of the line and its two neighbours, truncated to the
+narrowest width that is unambiguous in that file. `Edit` takes those anchors
+instead of retyped content:
+
+```json
+{ "file_path": "app.py", "hashline": [{ "start": "a3f9", "end": "7c1c", "new_string": "..." }] }
+```
+
+The span is inclusive; omit `end` to replace one line, pass an empty
+`new_string` to delete. Anchors are recomputed from disk when the edit runs, so
+a file that moved under the model fails to resolve and the patch is rejected
+rather than applied at stale coordinates. Exact-match `old_string` still works
+and is unchanged; anchors are a second shape, not a replacement. Turn the whole
+thing off with `"tools": {"hashline": false}` and reads go back to plain
+`cat -n`.
+
+**Symbols** answers structural questions with a parse tree rather than a
+regex — three modes, `outline` for one file's shape, `definition` for where a
+name is defined, `references` for where it is used:
+
+```
+Symbols(mode="references", symbol="handle")
+```
+
+Because it matches identifier nodes, the same word in a comment or a string
+literal never matches. It cannot resolve types, so an unrelated symbol with the
+same name in another file still does; it is tighter than `Grep`, not a language
+server. Python, TypeScript, JavaScript, Go and Rust.
+
+It needs grammars that are not installed by default, and the tool is simply not
+registered without them — its schema never enters the cached prefix advertising
+something that cannot run:
+
+```sh
+uv tool install "hx-cli[symbols]"
+```
+
+---
+
 ## Extending it
 
 **Skills** are directories containing `SKILL.md` with YAML frontmatter:
@@ -785,6 +876,68 @@ Or `hx mcp add local python server.py`. Tools arrive namespaced
 with a per-server timeout; one that is broken or slow logs a warning and is
 dropped rather than taking the session with it.
 
+**Hooks** are shell commands HX runs at named points in a turn. Four events:
+`PreToolUse`, `PostToolUse`, `UserPromptSubmit` and `Stop`.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "~/.hx/guard-bash.sh", "timeout": 10 }]
+      }
+    ],
+    "PostToolUse": [
+      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "ruff check --quiet" }] }
+    ]
+  }
+}
+```
+
+`matcher` is a regex matched against the whole tool name; omit it, or use `*`,
+to match every tool. The hook reads a JSON event on stdin — `session_id`,
+`cwd`, `hook_event_name`, and `tool_name`/`tool_input` where they apply — and
+answers with its exit code:
+
+| Exit | Means |
+|---|---|
+| `0` | allow |
+| `2` | block. stderr becomes the reason the model is given |
+| anything else | the hook is broken. Reported as a notice; the action proceeds |
+
+That last row is deliberate: a typo in a shell command must not be able to
+wedge a session. Only an explicit refusal stops anything.
+
+A hook may also print JSON on stdout: `{"decision": "block", "reason": "..."}`
+refuses, `{"updatedInput": {...}}` rewrites a tool's arguments before the
+permission engine sees them, and `{"additionalContext": "..."}` adds a note for
+the model to read. The format matches Claude Code's, so hooks already written
+against that work here unchanged.
+
+A worked example ships in the repository:
+[`examples/hooks/check.sh`](https://github.com/aletisunil/hx/blob/main/examples/hooks/check.sh)
+runs the checker a project already has — `ruff`, `tsc`, `go vet`, `cargo
+check` — against the one file the model just edited, and returns whatever it
+says as `additionalContext`. The model sees the errors appended to its own edit
+result and fixes them on the next turn, rather than discovering them at test
+time. It exits 0 either way: by `PostToolUse` the write has already landed, so
+refusing it would be an answer to something that already happened.
+
+```sh
+curl -o ~/.hx/check.sh https://raw.githubusercontent.com/aletisunil/hx/main/examples/hooks/check.sh
+chmod +x ~/.hx/check.sh
+```
+
+**Where hooks may be declared is a security boundary.** They are loaded from
+`~/.hx/settings.json` and `~/.hx/projects/<slug>/settings.local.json` only.
+Hooks in a project's checked-in `.hx/settings.json` are ignored and listed by
+`/hooks`, because that file arrives with a clone and cloning a repository must
+never be enough to run commands on the machine that cloned it. To adopt a
+shared hook, copy it into your own settings — a deliberate act by the person
+who will run it. Subagents inherit the parent's hooks, so a guard cannot be
+bypassed by delegating through `Task`.
+
 ---
 
 ## Development
@@ -807,6 +960,10 @@ OPENROUTER_API_KEY=... uv run pytest -m live tests/test_live.py
 # the Codex route draws on your ChatGPT subscription instead
 hx auth login openai-codex
 uv run pytest -m live tests/test_live_codex.py
+
+# and the Devin route on your Devin subscription
+hx auth login devin
+uv run pytest -m live tests/test_live_devin.py
 ```
 
 They are the only place the wire formats, streaming, tool use and a genuine
@@ -830,10 +987,11 @@ src/hx/
   cli.py config.py paths.py frontmatter.py git.py
   core/         loop, context assembly, compaction, late injection, sessions, usage
   auth/         credential store, OAuth flows, per-route resolution
-  providers/    OpenRouter, Codex, the model catalogue, a scripted provider for tests
-  tools/        Bash, Read, Write, Edit, Glob, Grep, TodoWrite, Task, WebSearch,
-                WebFetch, output capping
+  providers/    OpenRouter, Codex, Devin, the model catalogue, a scripted provider for tests
+  tools/        Bash, Read, Write, Edit, Glob, Grep, Symbols, TodoWrite, Task,
+                WebSearch, WebFetch, line anchors, output capping
   permissions/  rule engine, shell decomposition, Seatbelt/bubblewrap
+  hooks/        the four events, the trust boundary, subprocess execution
   skills/ agents/ mcp/
   keys.py       keybinding registry: ids, defaults, descriptions, user overrides
   term/         the renderer: raw mode, input decoding, the differ, the screen
@@ -896,12 +1054,13 @@ streaming with prefix caching and accurate cost accounting, session persistence
 and resume, the tool suite, the permission engine and OS sandbox, late
 injection, compaction, output capping, skills, subagents, MCP, and the TUI.
 
-Two routes to a model: an OpenRouter API key, or a ChatGPT Plus/Pro
-subscription over OAuth. The model id decides which.
+Three routes to a model: an OpenRouter API key, a ChatGPT Plus/Pro
+subscription over OAuth, or a Devin subscription over OAuth. The model id
+decides which.
 
 Published to PyPI as [`hx-cli`](https://pypi.org/project/hx-cli/), released
 from CI on a tag.
 
-The one thing still unproven in CI is a live call on either route: the `live`
-tests exist and cover both wire formats, tool use, reasoning replay and a
+The one thing still unproven in CI is a live call on any route: the `live`
+tests exist and cover all three wire formats, tool use, reasoning replay and a
 genuine cache hit, but they need a credential and are deselected by default.

{hx_cli-0.2.1 → hx_cli-0.2.3}/README.md

@@ -1,7 +1,7 @@
 # HX
 
-A terminal coding agent. Python core, its own terminal renderer, OpenRouter for
-models.
+An agent harness for the terminal. Python core, its own terminal renderer,
+OpenRouter for models.
 
 HX runs in your project directory, reads and edits your code, runs commands in
 a sandboxed shell, and shows you what every turn costs.
@@ -50,13 +50,14 @@ Requires Python 3.11+. macOS and Linux. Update with `hx upgrade`.
 
 ### Credentials
 
-HX reaches models over two routes. Which one serves a turn is decided by the
+HX reaches models over three routes. Which one serves a turn is decided by the
 model id alone, so "what paid for that" is always answerable by reading it:
 
 | Model id | Route | Billing |
 |---|---|---|
 | `anthropic/claude-sonnet-4.5`, `openai/gpt-5`, … | OpenRouter | per token, API key |
 | `openai-codex/gpt-5.6-terra` | ChatGPT Plus/Pro | your subscription |
+| `devin/swe-1-6`, `devin/claude-opus-5`, … | Devin | your subscription |
 
 Credentials live in `~/.hx/auth.json`, mode 0600, one entry per route.
 
@@ -150,6 +151,38 @@ They join the `/model` picker on the next start. HX cannot ask how large an
 unknown model's context window is, so it assumes a conservative 200k — that
 costs an accurate context gauge, not the use of the model.
 
+**Devin.** Sign in with the same browser flow the official `devin` CLI uses,
+and run every model your Devin plan includes - SWE-1.6, and whatever frontier
+models the plan offers - against the subscription:
+
+```sh
+hx auth login devin             # or /login inside the TUI
+hx --model devin/swe-1-6
+hx auth logout devin
+```
+
+**Devin Enterprise** signs in the same way: on the page that opens, choose
+"Log in with Devin for Enterprise", enter your company, and finish through its
+identity provider. Your admin has to grant the "Use Devin CLI" permission first.
+Usage counts toward the organization's allocation, and an enterprise tenant
+served from its own API server is followed there for both turns and the model
+list.
+
+The browser opens to `app.devin.ai` and redirects to a loopback listener on
+`127.0.0.1:59653`. Over SSH, paste the final redirect URL into the prompt
+instead. A Devin login does not refresh: when it expires, HX says so and asks
+you to sign in again. On a machine with no browser at all, a session token in
+`HX_DEVIN_API_KEY` or `DEVIN_API_KEY` is used when nothing is saved.
+
+Signing in fetches the account's own model list, and `/model` offers exactly
+that; `/models refresh` asks again. Devin publishes each reasoning depth as a
+model of its own - Claude Opus 5 High, Claude Opus 5 Max - and HX folds each
+family into one model, so `/effort` picks the depth on Devin exactly as it does
+on Codex. A fast lane or a 1M-context lane stays a separate model, since it
+changes what a turn costs or how much fits. Router models such as
+`devin/adaptive` are resolved to a concrete model on every turn by Devin itself.
+If the list cannot be fetched, `devin/swe-1-6` and `devin/swe-1-6-fast` stand in.
+
 **Web search.** Optional, and the one credential that is not a model route.
 It powers two tools:
 
@@ -235,7 +268,7 @@ hx --system-prompt @p.md    # replace the system prompt for one run
 hx --append-system-prompt "Always run the tests"   # add to it; repeatable
 hx mcp list|add|remove      # manage MCP servers
 hx auth [set|clear]         # manage the OpenRouter key
-hx auth login [provider]    # sign in (openrouter, openai-codex)
+hx auth login [provider]    # sign in (openrouter, openai-codex, devin)
 hx auth logout <provider>   # forget a stored credential
 hx docs [section]           # the manual; no argument lists its sections
 hx changelog [version]      # what shipped in each version
@@ -370,6 +403,7 @@ than being silently resolved.
 | `/skills` | installed skills |
 | `/agents` | subagent types |
 | `/mcp` | server status |
+| `/hooks` | configured hooks, and any that were refused |
 | `/theme [name]` | `dark`, `light`, `ansi`, or any theme in `~/.hx/themes` |
 | `/queue [steer <n>\|clear]` | messages waiting for the turn to end, and what to do with them |
 | `/copy` | copy the last reply to the clipboard |
@@ -487,7 +521,6 @@ along with the `.hx/.gitignore` it added to hide it.
 {
   "theme": "dark",                    // dark | light | ansi, or a file in ~/.hx/themes
   "quiet_startup": false,             // skip the startup header
-  "telemetry": false,
 
   "models": {
     "model": "anthropic/claude-sonnet-4.5",
@@ -530,10 +563,18 @@ along with the `.hx/.gitignore` it added to hide it.
   "tui": {
     "enterWhileBusy": "queue",        // queue | steer - what enter does mid-turn
     "fullscreen": false               // true takes the whole window (see /fullscreen)
+  },
+
+  "tools": {
+    "hashline": true                  // Read labels lines with content anchors Edit accepts
   }
 }
 ```
 
+`hooks` is configured in the same files but is deliberately not part of this
+merge: it is read per layer, and only from your own settings. See
+[Extending it](#extending-it).
+
 Environment overrides: `HX_MODEL`, `HX_SUBAGENT_MODEL`, `HX_MAX_TOKENS`,
 `HX_PERMISSION_MODE`, `HX_SANDBOX`, `HX_COMPACT_AT`, `HX_GIT_NOTICES`,
 `HX_THEME`, `HX_QUIET_STARTUP`. Also `HX_HOME` to relocate user state, `HX_TAVILY_API_KEY`
@@ -694,6 +735,54 @@ rest to the session directory, and hands the model that path to grep.
 
 ---
 
+## Reading and editing code
+
+**Line anchors.** `Read` labels every line with a short content hash:
+
+```
+     1 a3f9	def handle(request):
+     2 7c1c	    if request.method == "POST":
+```
+
+The anchor is a hash of the line and its two neighbours, truncated to the
+narrowest width that is unambiguous in that file. `Edit` takes those anchors
+instead of retyped content:
+
+```json
+{ "file_path": "app.py", "hashline": [{ "start": "a3f9", "end": "7c1c", "new_string": "..." }] }
+```
+
+The span is inclusive; omit `end` to replace one line, pass an empty
+`new_string` to delete. Anchors are recomputed from disk when the edit runs, so
+a file that moved under the model fails to resolve and the patch is rejected
+rather than applied at stale coordinates. Exact-match `old_string` still works
+and is unchanged; anchors are a second shape, not a replacement. Turn the whole
+thing off with `"tools": {"hashline": false}` and reads go back to plain
+`cat -n`.
+
+**Symbols** answers structural questions with a parse tree rather than a
+regex — three modes, `outline` for one file's shape, `definition` for where a
+name is defined, `references` for where it is used:
+
+```
+Symbols(mode="references", symbol="handle")
+```
+
+Because it matches identifier nodes, the same word in a comment or a string
+literal never matches. It cannot resolve types, so an unrelated symbol with the
+same name in another file still does; it is tighter than `Grep`, not a language
+server. Python, TypeScript, JavaScript, Go and Rust.
+
+It needs grammars that are not installed by default, and the tool is simply not
+registered without them — its schema never enters the cached prefix advertising
+something that cannot run:
+
+```sh
+uv tool install "hx-cli[symbols]"
+```
+
+---
+
 ## Extending it
 
 **Skills** are directories containing `SKILL.md` with YAML frontmatter:
@@ -750,6 +839,68 @@ Or `hx mcp add local python server.py`. Tools arrive namespaced
 with a per-server timeout; one that is broken or slow logs a warning and is
 dropped rather than taking the session with it.
 
+**Hooks** are shell commands HX runs at named points in a turn. Four events:
+`PreToolUse`, `PostToolUse`, `UserPromptSubmit` and `Stop`.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "~/.hx/guard-bash.sh", "timeout": 10 }]
+      }
+    ],
+    "PostToolUse": [
+      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "ruff check --quiet" }] }
+    ]
+  }
+}
+```
+
+`matcher` is a regex matched against the whole tool name; omit it, or use `*`,
+to match every tool. The hook reads a JSON event on stdin — `session_id`,
+`cwd`, `hook_event_name`, and `tool_name`/`tool_input` where they apply — and
+answers with its exit code:
+
+| Exit | Means |
+|---|---|
+| `0` | allow |
+| `2` | block. stderr becomes the reason the model is given |
+| anything else | the hook is broken. Reported as a notice; the action proceeds |
+
+That last row is deliberate: a typo in a shell command must not be able to
+wedge a session. Only an explicit refusal stops anything.
+
+A hook may also print JSON on stdout: `{"decision": "block", "reason": "..."}`
+refuses, `{"updatedInput": {...}}` rewrites a tool's arguments before the
+permission engine sees them, and `{"additionalContext": "..."}` adds a note for
+the model to read. The format matches Claude Code's, so hooks already written
+against that work here unchanged.
+
+A worked example ships in the repository:
+[`examples/hooks/check.sh`](https://github.com/aletisunil/hx/blob/main/examples/hooks/check.sh)
+runs the checker a project already has — `ruff`, `tsc`, `go vet`, `cargo
+check` — against the one file the model just edited, and returns whatever it
+says as `additionalContext`. The model sees the errors appended to its own edit
+result and fixes them on the next turn, rather than discovering them at test
+time. It exits 0 either way: by `PostToolUse` the write has already landed, so
+refusing it would be an answer to something that already happened.
+
+```sh
+curl -o ~/.hx/check.sh https://raw.githubusercontent.com/aletisunil/hx/main/examples/hooks/check.sh
+chmod +x ~/.hx/check.sh
+```
+
+**Where hooks may be declared is a security boundary.** They are loaded from
+`~/.hx/settings.json` and `~/.hx/projects/<slug>/settings.local.json` only.
+Hooks in a project's checked-in `.hx/settings.json` are ignored and listed by
+`/hooks`, because that file arrives with a clone and cloning a repository must
+never be enough to run commands on the machine that cloned it. To adopt a
+shared hook, copy it into your own settings — a deliberate act by the person
+who will run it. Subagents inherit the parent's hooks, so a guard cannot be
+bypassed by delegating through `Task`.
+
 ---
 
 ## Development
@@ -772,6 +923,10 @@ OPENROUTER_API_KEY=... uv run pytest -m live tests/test_live.py
 # the Codex route draws on your ChatGPT subscription instead
 hx auth login openai-codex
 uv run pytest -m live tests/test_live_codex.py
+
+# and the Devin route on your Devin subscription
+hx auth login devin
+uv run pytest -m live tests/test_live_devin.py
 ```
 
 They are the only place the wire formats, streaming, tool use and a genuine
@@ -795,10 +950,11 @@ src/hx/
   cli.py config.py paths.py frontmatter.py git.py
   core/         loop, context assembly, compaction, late injection, sessions, usage
   auth/         credential store, OAuth flows, per-route resolution
-  providers/    OpenRouter, Codex, the model catalogue, a scripted provider for tests
-  tools/        Bash, Read, Write, Edit, Glob, Grep, TodoWrite, Task, WebSearch,
-                WebFetch, output capping
+  providers/    OpenRouter, Codex, Devin, the model catalogue, a scripted provider for tests
+  tools/        Bash, Read, Write, Edit, Glob, Grep, Symbols, TodoWrite, Task,
+                WebSearch, WebFetch, line anchors, output capping
   permissions/  rule engine, shell decomposition, Seatbelt/bubblewrap
+  hooks/        the four events, the trust boundary, subprocess execution
   skills/ agents/ mcp/
   keys.py       keybinding registry: ids, defaults, descriptions, user overrides
   term/         the renderer: raw mode, input decoding, the differ, the screen
@@ -861,12 +1017,13 @@ streaming with prefix caching and accurate cost accounting, session persistence
 and resume, the tool suite, the permission engine and OS sandbox, late
 injection, compaction, output capping, skills, subagents, MCP, and the TUI.
 
-Two routes to a model: an OpenRouter API key, or a ChatGPT Plus/Pro
-subscription over OAuth. The model id decides which.
+Three routes to a model: an OpenRouter API key, a ChatGPT Plus/Pro
+subscription over OAuth, or a Devin subscription over OAuth. The model id
+decides which.
 
 Published to PyPI as [`hx-cli`](https://pypi.org/project/hx-cli/), released
 from CI on a tag.
 
-The one thing still unproven in CI is a live call on either route: the `live`
-tests exist and cover both wire formats, tool use, reasoning replay and a
+The one thing still unproven in CI is a live call on any route: the `live`
+tests exist and cover all three wire formats, tool use, reasoning replay and a
 genuine cache hit, but they need a credential and are deselected by default.