@nanobpm/nano-coder 0.34.0 → 0.35.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +48 -4
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -18,7 +18,8 @@ cargo install nano-coder # or build from source
18
18
  - **Providers**: OpenAI-compatible and Anthropic endpoints (remote or local), selected per model as `provider/model`, with retry/backoff
19
19
  - **Tool Calling**: Agent can invoke registered tools during conversation, including a real `bash` tool with timeouts and bounded output
20
20
  - **Sessions**: Append-only JSONL session logs with resume and input-ID deduplication
21
- - **Lifecycle Hooks**: 6 hook events for observing/intercepting agent behavior
21
+ - **Lifecycle Hooks**: 6 internal hook events for observing agent behavior, plus
22
+ Claude Code–compatible external user hooks loaded from `.claude/settings.json`
22
23
  - **Configuration**: TOML-based config file at `~/.config/nano-coder/config.toml`
23
24
  - **Commands**: `/help`, `/compact`, `/context`, `/verbosity`, `/settings`, `/tools`, `/skills`, `/queue`, `/restart`, `/exit`
24
25
  - **Streaming output**: answers stream in, thinking shows collapsed (Ctrl-O expands it), tool calls show inline
@@ -139,7 +140,8 @@ src/
139
140
  ├── main.rs # Single binary entry point (interactive + ACP modes)
140
141
  ├── agent.rs # Agent core: conversation management, tool execution loop
141
142
  ├── acp.rs # ACP JSON-RPC protocol handler
142
- ├── hooks.rs # Lifecycle hook registry and event system
143
+ ├── hooks.rs # Internal (observe-only) lifecycle hook registry and events
144
+ ├── claude_hooks.rs # External Claude Code–compatible user hooks engine
143
145
  ├── tools.rs # Tool registration and dispatch system
144
146
  ├── llm.rs # Provider-neutral messages and the async LLMClient trait
145
147
  ├── providers/ # Provider registry + presets, HTTP transport with retries
@@ -181,7 +183,14 @@ Mode selection: `--acp` flag enables ACP headless mode; default is interactive C
181
183
 
182
184
  ## Lifecycle Hooks
183
185
 
184
- The harness exposes 6 lifecycle hook events:
186
+ nano-coder has two hook systems.
187
+
188
+ ### Internal hooks (observe-only)
189
+
190
+ The harness exposes 6 internal lifecycle hook events for in-process Rust
191
+ callbacks. These are **observe-only**: a callback can inspect the event payload
192
+ (for logging, metrics, debugging) but cannot block, modify, or redirect the
193
+ agent. They are registered programmatically against `agent.hooks()`.
185
194
 
186
195
  | Hook | When it fires |
187
196
  |------|---------------|
@@ -192,6 +201,36 @@ The harness exposes 6 lifecycle hook events:
192
201
  | `before_tool_call` | Before executing a tool |
193
202
  | `after_tool_call` | After tool execution completes |
194
203
 
204
+ ### External user hooks (Claude Code–compatible)
205
+
206
+ nano-coder also runs **external user hooks** that follow the
207
+ [Claude Code hooks protocol](https://docs.claude.com/en/docs/claude-code/hooks),
208
+ so existing Claude Code hook configurations work unchanged. These are loaded,
209
+ in order, from:
210
+
211
+ 1. `[hooks]` in nano-coder's own user config (`config.toml`), in Claude's structure
212
+ 2. `~/.claude/settings.json` (your Claude Code user settings; disable with `claude_user_hooks = false`)
213
+ 3. `<project>/.claude/settings.json` (project settings, committed)
214
+ 4. `<project>/.claude/settings.local.json` (project-local, git-ignored)
215
+
216
+ Each hook is a `command` that nano-coder runs as a subprocess, passing the
217
+ event payload as JSON on stdin and interpreting its exit code and (optional)
218
+ JSON stdout per Claude's protocol. Hooks can **block** a tool call or prompt,
219
+ **modify** a tool's input, or **inject additional context**. nano-coder
220
+ translates its tool names (`bash`→`Bash`, `read_file`→`Read`, `write_file`→
221
+ `Write`, `edit_file`→`Edit`, `grep`→`Grep`, `glob`→`Glob`) and the `file_path`/
222
+ `path` argument so Claude-authored matchers and scripts match correctly.
223
+
224
+ Supported events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`,
225
+ `PostToolUse`, and `Stop`. A `PreToolUse` hook that fails (crashes, times out,
226
+ or exits non-zero) **fails closed** and blocks the tool call; failures in other
227
+ events are non-blocking.
228
+
229
+ Run `/hooks` at the prompt to list the loaded hooks, which files they came
230
+ from, and any that were skipped (e.g. unsupported events reserved for later
231
+ phases). Disable them with `--no-hooks`, or granularly via the
232
+ `disable_hooks`, `disable_project_hooks`, and `claude_user_hooks` settings.
233
+
195
234
  ## Built-in Tools
196
235
 
197
236
  - `get_time` - Get current date and time
@@ -333,6 +372,7 @@ argument: a type-ahead list narrows as you type and Tab completes it.
333
372
  - `/skills` - List the skills the agent can load, where each lives, and any loading warnings
334
373
  - `/plan` - Show the agent's task plan with all notes
335
374
  - `/memory [forget ID]` - List cross-session memories with their ids, or delete one by id (see [Memory](#memory))
375
+ - `/hooks` - List the loaded external user hooks (from `.claude/settings.json` and friends), the files they came from, and any skipped entries (see [Lifecycle Hooks](#lifecycle-hooks))
336
376
  - `/queue [list|add text|remove N...|edit N text|clear]` - Show or edit the queued messages. Works while a turn runs, so a queued message can be removed or rewritten before it is sent.
337
377
  - `/model [provider/model]` - Show the current model and pick a new one. The list starts with the last four models you used (the current one marked; the previous one highlighted, so `/model` then Enter switches back), then the providers: pick a provider to scroll its model list (Esc steps back). With an argument, switches directly (conversation is kept). Typing `/model ` shows a type-ahead of the current model, recently used models, and each configured provider's default model; Tab completes (a bare provider name completes to its default model). Recently used models are kept in `~/.local/share/nano-coder/recent-models.json`
338
378
  - `/mode [normal|plan|auto]` - Show or set the agent mode (Shift+Tab cycles it, at the prompt or mid-turn):
@@ -940,7 +980,7 @@ agent.tools().register(tool_def, Box::new(|args| {
940
980
 
941
981
  The model sees a JSON string result as plain text and any other value as serialized JSON.
942
982
 
943
- ### Adding Hooks
983
+ ### Adding internal (observe-only) hooks
944
984
 
945
985
  ```rust
946
986
  agent.hooks().register(HookEvent::BeforeToolCall, Box::new(|ctx| {
@@ -949,6 +989,10 @@ agent.hooks().register(HookEvent::BeforeToolCall, Box::new(|ctx| {
949
989
  }));
950
990
  ```
951
991
 
992
+ These callbacks observe only; to block, modify, or add context to a tool call
993
+ or prompt, use the external Claude-compatible user hooks described under
994
+ [Lifecycle Hooks](#lifecycle-hooks).
995
+
952
996
  ### Custom LLM Client
953
997
 
954
998
  Implement the async `LLMClient` trait (or add a `ProviderKind` in `src/providers/`):
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nanobpm/nano-coder",
3
- "version": "0.34.0",
3
+ "version": "0.35.0",
4
4
  "description": "A 6MB coding agent. Run a fleet on your laptop.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -31,9 +31,9 @@
31
31
  "node": ">=18"
32
32
  },
33
33
  "optionalDependencies": {
34
- "@nanobpm/nano-coder-darwin-arm64": "0.34.0",
35
- "@nanobpm/nano-coder-darwin-x64": "0.34.0",
36
- "@nanobpm/nano-coder-linux-arm64": "0.34.0",
37
- "@nanobpm/nano-coder-linux-x64": "0.34.0"
34
+ "@nanobpm/nano-coder-darwin-arm64": "0.35.0",
35
+ "@nanobpm/nano-coder-darwin-x64": "0.35.0",
36
+ "@nanobpm/nano-coder-linux-arm64": "0.35.0",
37
+ "@nanobpm/nano-coder-linux-x64": "0.35.0"
38
38
  }
39
39
  }