From 1cd039979c2ed2f793f6d4d2b2d7877aff4b6bbd Mon Sep 17 00:00:00 2001
From: Cannon07 <jayshitre@gmail.com>
Date: Tue, 19 May 2026 11:55:38 +0530
Subject: [PATCH 1/3] feat: in-process Lua core handler for claudecode (#47,
 phase 3)

Replaces bin/core-pre-tool.sh's role for Claude Code with an in-process
Lua orchestrator (lua/code-preview/pre_tool/), invoked through a single
RPC call from the per-OS hook entry. Eliminates the per-proposal nvim
cold-start (~50-100ms) and collapses the 5+ RPC round-trips per
proposal into one. apply-edit / apply-multi-edit / apply-patch move to
lua/code-preview/apply/ and are called in-process; bin/ retains thin
shims for external callers.

The bash core handler stays in place for opencode / codex / copilot;
they flip in follow-up PRs. See docs/adr/0005 for the design rationale,
including why we run in-process rather than as a headless worker.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 CONTEXT.md                                    |   6 +-
 backends/claudecode/code-close-diff.sh        |  27 +-
 backends/claudecode/code-preview-diff.sh      |  31 ++-
 bin/apply-edit.lua                            |  55 +---
 bin/apply-multi-edit.lua                      |  41 +--
 bin/apply-patch.lua                           | 237 ++--------------
 docs/adr/0004-config-lives-only-in-neovim.md  |   2 +-
 docs/adr/0005-core-handler-runs-in-process.md |  20 ++
 lua/code-preview/apply/edit.lua               |  51 ++++
 lua/code-preview/apply/multi_edit.lua         |  36 +++
 lua/code-preview/apply/patch.lua              | 191 +++++++++++++
 lua/code-preview/post_tool.lua                |  89 ++++++
 lua/code-preview/pre_tool/bash_detect.lua     | 254 ++++++++++++++++++
 lua/code-preview/pre_tool/emitters.lua        |  43 +++
 lua/code-preview/pre_tool/init.lua            | 251 +++++++++++++++++
 lua/code-preview/pre_tool/normalisers.lua     |  36 +++
 tests/plugin/pre_tool_bash_detect_spec.lua    |  82 ++++++
 tests/plugin/pre_tool_handle_spec.lua         |  87 ++++++
 tests/plugin/pre_tool_normaliser_spec.lua     |  29 ++
 19 files changed, 1273 insertions(+), 295 deletions(-)
 create mode 100644 docs/adr/0005-core-handler-runs-in-process.md
 create mode 100644 lua/code-preview/apply/edit.lua
 create mode 100644 lua/code-preview/apply/multi_edit.lua
 create mode 100644 lua/code-preview/apply/patch.lua
 create mode 100644 lua/code-preview/post_tool.lua
 create mode 100644 lua/code-preview/pre_tool/bash_detect.lua
 create mode 100644 lua/code-preview/pre_tool/emitters.lua
 create mode 100644 lua/code-preview/pre_tool/init.lua
 create mode 100644 lua/code-preview/pre_tool/normalisers.lua
 create mode 100644 tests/plugin/pre_tool_bash_detect_spec.lua
 create mode 100644 tests/plugin/pre_tool_handle_spec.lua
 create mode 100644 tests/plugin/pre_tool_normaliser_spec.lua

diff --git a/CONTEXT.md b/CONTEXT.md
index 29b83c3..4485e09 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -75,7 +75,7 @@ Job: take the agent's native hook payload, normalise it into the shape the [core
 
 ## Core handler
 
-The agent-neutral pipeline that, given a normalised proposal, decides whether to show a preview, computes the original and proposed file content, and makes the [RPC](#rpc) call into the running Neovim. Today: `bin/core-pre-tool.sh` and `bin/core-post-tool.sh`. Issue #47 phases 3 and 4 replace these with Lua equivalents run via `nvim --headless -l`; the role stays the same.
+The agent-neutral pipeline that, given a normalised proposal, decides whether to show a preview, computes the original and proposed file content, and makes the [RPC](#rpc) call into the running Neovim. Today: `bin/core-pre-tool.sh` and `bin/core-post-tool.sh`. Issue #47 phases 3 and 4 fold the core handler into in-process Lua (`lua/code-preview/pre_tool.lua` / `post_tool.lua`), invoked through a single RPC call from the per-agent [hook entry](#hook-entry); the orchestration role stays the same but no longer runs in a separate process. See [ADR-0005](docs/adr/0005-core-handler-runs-in-process.md).
 
 The core handler is where shell-write detection, `visible_only` gating, and `permissionDecision` emission live — everything that doesn't depend on which agent fired the hook.
 
@@ -174,6 +174,8 @@ An [RPC](#rpc) call the [core handler](#core-handler) issues to the running Neov
 
 The pattern exists because the bash layer holds no config of its own — see [ADR-0004](docs/adr/0004-config-lives-only-in-neovim.md). If Neovim is unreachable, the hook degrades safely (no logging, no [review gate](#review-gate), no visibility filter).
 
+After issue #47 phase 3, the hook context query collapses into a local function call inside the in-process [core handler](#core-handler); the RPC form survives only for callers that still live outside the user's Neovim (e.g. a backend that hasn't yet flipped to the Lua entry point).
+
 ## Headless worker
 
 A short-lived Neovim spawned with `nvim --headless -l <script>.lua` to do work *outside* the user's running Neovim. Headless workers have no UI, no access to the user's `M.config` or open buffers, and communicate via stdin / stdout / exit code or via [RPC](#rpc) back to the user's instance.
@@ -184,7 +186,7 @@ Today's headless workers:
 - `bin/apply-multi-edit.lua` — same for `MultiEdit`.
 - `bin/apply-patch.lua` — parses the custom patch format and emits per-file orig/prop tempfiles for `ApplyPatch`.
 
-After issue #47 phases 3 and 4, `bin/core-pre-tool.lua` and `bin/core-post-tool.lua` will join this category — the entire [core handler](#core-handler) becomes a headless worker. At that point, "bash core handler" goes away as a concept and "headless worker" is *the* extra-process model.
+Issue #47 phases 3 and 4 do **not** add the core handler to this list. After an early design pass we chose to fold the handler into in-process Lua instead of a new headless worker, to eliminate the per-proposal cold-start and the chain of small RPC calls back into the user's Neovim. See [ADR-0005](docs/adr/0005-core-handler-runs-in-process.md). After phases 3/4 land, "bash core handler" goes away and the apply-* scripts remain the canonical examples of headless workers.
 
 ## In-process Lua vs headless Lua
 
diff --git a/backends/claudecode/code-close-diff.sh b/backends/claudecode/code-close-diff.sh
index 6522ce6..beaf641 100755
--- a/backends/claudecode/code-close-diff.sh
+++ b/backends/claudecode/code-close-diff.sh
@@ -1,8 +1,27 @@
 #!/usr/bin/env bash
-# code-close-diff.sh — PostToolUse hook adapter for Claude Code
-# Delegates to core-post-tool.sh with the Claude Code backend flag.
+# code-close-diff.sh — PostToolUse hook entry for Claude Code.
+#
+# After issue #47 phase 3, this shim makes a single RPC call into the
+# in-process orchestrator (lua/code-preview/post_tool.lua) and exits. The
+# orchestrator clears the changes registry, closes any open preview for the
+# affected file, and refreshes neo-tree.
+#
+# When Neovim is unreachable, the shim abstains silently (exit 0).
+
+set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 BIN_DIR="$SCRIPT_DIR/../../bin"
-export CODE_PREVIEW_BACKEND="claudecode"
-exec "$BIN_DIR/core-post-tool.sh"
+
+INPUT="$(cat)"
+CWD="$(printf '%s' "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)"
+
+source "$BIN_DIR/nvim-socket.sh" "$CWD" 2>/dev/null || true
+source "$BIN_DIR/nvim-call.sh"
+
+if [[ -z "${NVIM_SOCKET:-}" ]]; then
+  exit 0
+fi
+
+ARGS="$(jq -nc --argjson r "$INPUT" --arg b claudecode '[$r, $b]')"
+nvim_call code-preview.post_tool handle "$ARGS" >/dev/null
diff --git a/backends/claudecode/code-preview-diff.sh b/backends/claudecode/code-preview-diff.sh
index 99fb0ef..24cef88 100755
--- a/backends/claudecode/code-preview-diff.sh
+++ b/backends/claudecode/code-preview-diff.sh
@@ -1,8 +1,31 @@
 #!/usr/bin/env bash
-# code-preview-diff.sh — PreToolUse hook adapter for Claude Code
-# Delegates to core-pre-tool.sh with the Claude Code backend flag.
+# code-preview-diff.sh — PreToolUse hook entry for Claude Code.
+#
+# After issue #47 phase 3, this shim does almost nothing: it discovers the
+# running Neovim's socket and makes a single RPC call into the in-process
+# orchestrator (lua/code-preview/pre_tool/init.lua), then prints whatever the
+# orchestrator returns. The 600 lines of bash that used to live in
+# core-pre-tool.sh are gone.
+#
+# When Neovim is unreachable, the shim abstains: exit 0 with no stdout.
+# Claude Code falls back to its native permission flow as if the plugin
+# weren't installed. See docs/adr/0005-core-handler-runs-in-process.md.
+
+set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 BIN_DIR="$SCRIPT_DIR/../../bin"
-export CODE_PREVIEW_BACKEND="claudecode"
-exec "$BIN_DIR/core-pre-tool.sh"
+
+INPUT="$(cat)"
+CWD="$(printf '%s' "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)"
+
+# Socket discovery — silent failure is fine, we abstain below.
+source "$BIN_DIR/nvim-socket.sh" "$CWD" 2>/dev/null || true
+source "$BIN_DIR/nvim-call.sh"
+
+if [[ -z "${NVIM_SOCKET:-}" ]]; then
+  exit 0
+fi
+
+ARGS="$(jq -nc --argjson r "$INPUT" --arg b claudecode '[$r, $b]')"
+nvim_call code-preview.pre_tool handle "$ARGS"
diff --git a/bin/apply-edit.lua b/bin/apply-edit.lua
index 90de5b9..c67183a 100755
--- a/bin/apply-edit.lua
+++ b/bin/apply-edit.lua
@@ -1,10 +1,20 @@
 #!/usr/bin/env -S nvim --headless -l
--- apply-edit.lua — Apply a single Edit (old_string → new_string) to a file.
+-- apply-edit.lua — Headless-CLI shim around lua/code-preview/apply/edit.lua.
 --
 -- Usage (via nvim --headless -l):
 --   nvim --headless -l apply-edit.lua <file_path> <old_string> <new_string> <replace_all> <output_path>
 --
 -- replace_all: "true" or "false"
+--
+-- The real implementation is in-process Lua at lua/code-preview/apply/edit.lua.
+-- This shim survives only for external callers (legacy hooks, tests invoking
+-- the script directly). After issue #47 phase 3, pre_tool.lua calls the module
+-- directly without spawning a second nvim.
+
+local script_dir = debug.getinfo(1, "S").source:sub(2):match("(.*)/")
+vim.opt.runtimepath:prepend(script_dir .. "/..")
+
+local apply_edit = require("code-preview.apply.edit")
 
 local file_path   = arg[1]
 local old_string  = arg[2]
@@ -12,49 +22,8 @@ local new_string  = arg[3]
 local replace_all = arg[4] == "true"
 local output_path = arg[5]
 
--- Read the file (empty string if it does not exist yet)
-local content = ""
-local fh = io.open(file_path, "r")
-if fh then
-  content = fh:read("*a")
-  fh:close()
-end
-
--- Literal replacement (string.find plain=true prevents pattern interpretation)
-if replace_all then
-  -- Replace all occurrences
-  local result = {}
-  local search_start = 1
-  if old_string == "" then
-    -- Empty old_string: prepend new_string (handles "insert into empty file")
-    result = { new_string, content }
-  else
-    while true do
-      local s, e = string.find(content, old_string, search_start, true)
-      if not s then
-        table.insert(result, content:sub(search_start))
-        break
-      end
-      table.insert(result, content:sub(search_start, s - 1))
-      table.insert(result, new_string)
-      search_start = e + 1
-    end
-  end
-  content = table.concat(result)
-else
-  -- Replace first occurrence only
-  if old_string == "" then
-    -- Empty old_string: prepend new_string (handles "insert into empty file")
-    content = new_string .. content
-  else
-    local s, e = string.find(content, old_string, 1, true)
-    if s then
-      content = content:sub(1, s - 1) .. new_string .. content:sub(e + 1)
-    end
-  end
-end
+local content = apply_edit.apply(file_path, old_string, new_string, replace_all)
 
--- Write the result
 local out = assert(io.open(output_path, "w"))
 out:write(content)
 out:close()
diff --git a/bin/apply-multi-edit.lua b/bin/apply-multi-edit.lua
index bf68f12..2711bb0 100755
--- a/bin/apply-multi-edit.lua
+++ b/bin/apply-multi-edit.lua
@@ -1,50 +1,27 @@
 #!/usr/bin/env -S nvim --headless -l
--- apply-multi-edit.lua — Apply a MultiEdit (multiple edits) to a file.
+-- apply-multi-edit.lua — Headless-CLI shim around lua/code-preview/apply/multi_edit.lua.
 --
 -- Usage (via nvim --headless -l):
 --   nvim --headless -l apply-multi-edit.lua <hook_json_string> <output_path>
 --
--- arg[1]: full hook JSON (the same JSON that arrives on stdin for the hook)
--- arg[2]: path to write the resulting file content
+-- The real implementation is in-process Lua at lua/code-preview/apply/multi_edit.lua.
 
-local hook_json  = arg[1]
+local script_dir = debug.getinfo(1, "S").source:sub(2):match("(.*)/")
+vim.opt.runtimepath:prepend(script_dir .. "/..")
+
+local apply_multi_edit = require("code-preview.apply.multi_edit")
+
+local hook_json   = arg[1]
 local output_path = arg[2]
 
--- Parse JSON via vim.json (always available in Neovim)
 local ok, input = pcall(vim.json.decode, hook_json)
 if not ok then
   io.stderr:write("apply-multi-edit.lua: failed to parse JSON: " .. tostring(input) .. "\n")
   os.exit(1)
 end
 
-local file_path = input.tool_input.file_path
-local edits     = input.tool_input.edits or {}
-
--- Read the file (empty string if it does not exist yet)
-local content = ""
-local fh = io.open(file_path, "r")
-if fh then
-  content = fh:read("*a")
-  fh:close()
-end
-
--- Apply each edit sequentially (literal, not pattern-based)
-for _, edit in ipairs(edits) do
-  local old = edit.old_string or ""
-  local new = edit.new_string or ""
-  if old == "" then
-    -- Empty old_string → prepend new content (matches Python behaviour)
-    content = new .. content
-  else
-    local s, e = string.find(content, old, 1, true)
-    if s then
-      content = content:sub(1, s - 1) .. new .. content:sub(e + 1)
-    end
-    -- If not found, skip silently (matches Python behaviour)
-  end
-end
+local content = apply_multi_edit.apply(input.tool_input.file_path, input.tool_input.edits or {})
 
--- Write the result
 local out = assert(io.open(output_path, "w"))
 out:write(content)
 out:close()
diff --git a/bin/apply-patch.lua b/bin/apply-patch.lua
index eda519e..5123462 100644
--- a/bin/apply-patch.lua
+++ b/bin/apply-patch.lua
@@ -1,23 +1,21 @@
 #!/usr/bin/env -S nvim --headless -l
---- apply-patch.lua — Parse custom patch format and produce per-file original/proposed pairs
----
---- Usage: nvim --headless -l apply-patch.lua <patch_json> <cwd> <output_dir>
----
---- Reads the patch text from a JSON file ({"patch_text": "..."}), parses the
---- custom patch format used by OpenCode/GPT models:
----
----   *** Begin Patch
----   *** Update File: path/to/file
----   @@
----   -old line
----   +new line
----    context line
----   *** End Patch
----
---- Writes per-file results to output_dir:
----   <output_dir>/files.json        — list of {path, orig, prop} objects
----   <output_dir>/<hash>-orig       — original content
----   <output_dir>/<hash>-prop       — proposed content
+-- apply-patch.lua — Headless-CLI shim around lua/code-preview/apply/patch.lua.
+--
+-- Usage: nvim --headless -l apply-patch.lua <patch_json> <cwd> <output_dir>
+--
+-- Reads the patch text from a JSON file ({"patch_text": "..."}), parses via
+-- the in-process module, writes per-file results to output_dir:
+--
+--   <output_dir>/files.json   — list of {path, rel_path, action, orig, prop}
+--   <output_dir>/<NN>-orig    — original content
+--   <output_dir>/<NN>-prop    — proposed content
+--
+-- The real implementation is in-process Lua at lua/code-preview/apply/patch.lua.
+
+local script_dir = debug.getinfo(1, "S").source:sub(2):match("(.*)/")
+vim.opt.runtimepath:prepend(script_dir .. "/..")
+
+local apply_patch = require("code-preview.apply.patch")
 
 local patch_json_path = arg[1]
 local cwd = arg[2]
@@ -29,7 +27,6 @@ if not patch_json_path or not cwd or not output_dir then
   return
 end
 
--- Read patch text from JSON file
 local f = io.open(patch_json_path, "r")
 if not f then
   io.stderr:write("Cannot open patch JSON: " .. patch_json_path .. "\n")
@@ -46,214 +43,36 @@ if not ok or not data.patch_text then
   return
 end
 
-local patch_text = data.patch_text
-
--- Parse the custom patch format into file sections
-local files = {}
-local current_file = nil
-local current_action = nil -- "update", "add", "delete"
-
-for line in (patch_text .. "\n"):gmatch("([^\n]*)\n") do
-  local update_path = line:match("^%*%*%* Update File:%s*(.+)$")
-  local add_path = line:match("^%*%*%* Add File:%s*(.+)$")
-  local delete_path = line:match("^%*%*%* Delete File:%s*(.+)$")
-
-  if update_path then
-    current_file = { path = update_path:gsub("%s+$", ""), action = "update", hunks = {}, current_hunk = nil }
-    table.insert(files, current_file)
-    current_action = "update"
-  elseif add_path then
-    current_file = { path = add_path:gsub("%s+$", ""), action = "add", hunks = {}, current_hunk = nil }
-    table.insert(files, current_file)
-    current_action = "add"
-  elseif delete_path then
-    current_file = { path = delete_path:gsub("%s+$", ""), action = "delete", hunks = {}, current_hunk = nil }
-    table.insert(files, current_file)
-    current_action = "delete"
-  elseif line:match("^@@") and current_file then
-    -- Start a new hunk
-    current_file.current_hunk = { lines = {} }
-    table.insert(current_file.hunks, current_file.current_hunk)
-  elseif line == "*** End Patch" or line == "*** Begin Patch" then
-    current_file = nil
-  elseif current_file then
-    -- `*** Add File:` in the GPT patch format has no `@@` marker — content
-    -- lines follow directly. Lazy-create a hunk on the first content line
-    -- so those lines aren't dropped, without leaving an empty leading hunk
-    -- when `@@` *is* present.
-    if not current_file.current_hunk and current_action == "add" then
-      current_file.current_hunk = { lines = {} }
-      table.insert(current_file.hunks, current_file.current_hunk)
-    end
-    if current_file.current_hunk then
-      table.insert(current_file.current_hunk.lines, line)
-    end
-  end
-end
-
--- Resolve file path relative to cwd
-local function resolve_path(path)
-  if path:sub(1, 1) == "/" then
-    return path
-  end
-  return cwd .. "/" .. path
-end
-
--- Read file content as lines
-local function read_lines(path)
-  local fh = io.open(path, "r")
-  if not fh then
-    return {}
-  end
-  local lines = {}
-  for line in fh:lines() do
-    table.insert(lines, line)
-  end
-  fh:close()
-  return lines
-end
-
--- Apply hunks to original lines to produce proposed lines
-local function apply_hunks(orig_lines, hunks)
-  if #hunks == 0 then
-    return orig_lines
-  end
-
-  local result = {}
-  local orig_idx = 1
-
-  for _, hunk in ipairs(hunks) do
-    -- Each hunk has context lines (space-prefixed), removals (-), additions (+)
-    -- Context lines help us find position in the original file
-
-    -- First, find where this hunk starts in the original by matching context
-    local hunk_lines = hunk.lines
-
-    -- Collect the context/remove pattern to locate position
-    local match_lines = {}
-    for _, hl in ipairs(hunk_lines) do
-      local prefix = hl:sub(1, 1)
-      if prefix == " " then
-        table.insert(match_lines, { type = "context", text = hl:sub(2) })
-      elseif prefix == "-" then
-        table.insert(match_lines, { type = "remove", text = hl:sub(2) })
-      elseif prefix == "+" then
-        table.insert(match_lines, { type = "add", text = hl:sub(2) })
-      else
-        -- Lines without a recognized prefix are treated as context
-        table.insert(match_lines, { type = "context", text = hl })
-      end
-    end
-
-    -- Find the start position by matching context/remove lines against original
-    local first_match_text = nil
-    for _, ml in ipairs(match_lines) do
-      if ml.type == "context" or ml.type == "remove" then
-        first_match_text = ml.text
-        break
-      end
-    end
-
-    if first_match_text then
-      -- Advance orig_idx to find the matching line
-      while orig_idx <= #orig_lines do
-        if orig_lines[orig_idx] == first_match_text then
-          break
-        end
-        -- Copy non-matching lines to result (they're before this hunk)
-        table.insert(result, orig_lines[orig_idx])
-        orig_idx = orig_idx + 1
-      end
-    end
-
-    -- Apply the hunk
-    for _, ml in ipairs(match_lines) do
-      if ml.type == "context" then
-        table.insert(result, ml.text)
-        orig_idx = orig_idx + 1
-      elseif ml.type == "remove" then
-        -- Skip original line (don't add to result)
-        orig_idx = orig_idx + 1
-      elseif ml.type == "add" then
-        table.insert(result, ml.text)
-        -- Don't advance orig_idx
-      end
-    end
-  end
-
-  -- Copy remaining original lines
-  while orig_idx <= #orig_lines do
-    table.insert(result, orig_lines[orig_idx])
-    orig_idx = orig_idx + 1
-  end
-
-  return result
-end
-
--- Write lines to a file
 local function write_lines(path, lines)
   local fh = io.open(path, "w")
-  if not fh then
-    return false
-  end
+  if not fh then return false end
   for i, line in ipairs(lines) do
     fh:write(line)
-    if i < #lines then
-      fh:write("\n")
-    end
-  end
-  -- Add trailing newline
-  if #lines > 0 then
-    fh:write("\n")
+    if i < #lines then fh:write("\n") end
   end
+  if #lines > 0 then fh:write("\n") end
   fh:close()
   return true
 end
 
--- Process each file section
+local files = apply_patch.parse(data.patch_text, cwd)
 local results = {}
-for i, file_section in ipairs(files) do
-  local abs_path = resolve_path(file_section.path)
+
+for i, file in ipairs(files) do
   local tag = string.format("%02d", i)
   local orig_out = output_dir .. "/" .. tag .. "-orig"
   local prop_out = output_dir .. "/" .. tag .. "-prop"
-
-  if file_section.action == "delete" then
-    local orig_lines = read_lines(abs_path)
-    write_lines(orig_out, orig_lines)
-    write_lines(prop_out, {})
-  elseif file_section.action == "add" then
-    write_lines(orig_out, {})
-    -- For add, all hunk lines should be additions
-    local new_lines = {}
-    for _, hunk in ipairs(file_section.hunks) do
-      for _, hl in ipairs(hunk.lines) do
-        if hl:sub(1, 1) == "+" then
-          table.insert(new_lines, hl:sub(2))
-        elseif hl:sub(1, 1) ~= "-" then
-          -- Bare lines (no prefix) in add mode are content
-          table.insert(new_lines, hl)
-        end
-      end
-    end
-    write_lines(prop_out, new_lines)
-  else -- update
-    local orig_lines = read_lines(abs_path)
-    write_lines(orig_out, orig_lines)
-    local proposed = apply_hunks(orig_lines, file_section.hunks)
-    write_lines(prop_out, proposed)
-  end
-
+  write_lines(orig_out, file.orig)
+  write_lines(prop_out, file.prop)
   table.insert(results, {
-    path = abs_path,
-    rel_path = file_section.path,
-    action = file_section.action,
+    path = file.path,
+    rel_path = file.rel_path,
+    action = file.action,
     orig = orig_out,
     prop = prop_out,
   })
 end
 
--- Write the file list as JSON
 local results_path = output_dir .. "/files.json"
 local rf = io.open(results_path, "w")
 if rf then
diff --git a/docs/adr/0004-config-lives-only-in-neovim.md b/docs/adr/0004-config-lives-only-in-neovim.md
index 831d1d5..37ec3aa 100644
--- a/docs/adr/0004-config-lives-only-in-neovim.md
+++ b/docs/adr/0004-config-lives-only-in-neovim.md
@@ -14,5 +14,5 @@ The reason: keeping a second copy of config on the bash side creates two ways to
 
 - Per-hook latency includes at least one RPC round-trip (often two: `log.state` early + `hook_context` later). Acceptable today; if the cost ever bites, the two queries can be merged into one.
 - The bash handler's behaviour without Neovim is a real fallback path, not a bug — it must remain safe and silent. Tests should exercise the "no nvim" branch.
-- After issue #47 phases 3 and 4, the [core handler](../../CONTEXT.md#core-handler) runs as Lua via `nvim --headless -l`. The hook-context-query pattern still applies, but the call becomes an in-process function call rather than an RPC. The principle (config in Neovim, fetched on demand) does not change.
+- After issue #47 phases 3 and 4, the [core handler](../../CONTEXT.md#core-handler) runs in-process inside the user's Neovim (see [ADR-0005](0005-core-handler-runs-in-process.md)). The hook-context-query collapses into a local function call; the RPC form survives only for callers that still live outside the user's Neovim. The principle (config in Neovim, fetched on demand) does not change.
 - New config keys that the bash side might need must be added to `hook_context()`'s return shape — not silently exported to the environment or written to a side file.
diff --git a/docs/adr/0005-core-handler-runs-in-process.md b/docs/adr/0005-core-handler-runs-in-process.md
new file mode 100644
index 0000000..8b7f62a
--- /dev/null
+++ b/docs/adr/0005-core-handler-runs-in-process.md
@@ -0,0 +1,20 @@
+# Core handler runs in-process inside the user's Neovim, not as a headless worker
+
+Issue #47 phase 3 ports the bash [core handler](../../CONTEXT.md#core-handler) (`bin/core-pre-tool.sh`, ~600 lines) to Lua. The issue text framed the port as a like-for-like swap to a [headless worker](../../CONTEXT.md#headless-worker) (`nvim --headless -l bin/core-pre-tool.lua`). We instead fold the handler into in-process Lua (`lua/code-preview/pre_tool.lua`), invoked through a single [RPC](../../CONTEXT.md#rpc) call from the per-agent [hook entry](../../CONTEXT.md#hook-entry).
+
+The reason: the bash handler is a headless worker only because bash had no other option. Its job — mutating the [changes](../../CONTEXT.md#change) registry, opening [previews](../../CONTEXT.md#preview), driving neo-tree [reveal](../../CONTEXT.md#reveal) — is entirely in-process work that today reaches the user's Neovim through a chain of small RPC calls (`log.state`, `hook_context`, `changes.set`, `neo_tree.refresh`, `diff.show_diff`). Moving the orchestration *into* the Neovim it's already mutating eliminates the cold-start (50–100ms × every proposal) and collapses 5+ RPC round-trips per proposal into one fat call.
+
+## Considered Options
+
+- **A — Lua headless worker** (the issue's literal proposal). `bin/core-pre-tool.lua` spawned per proposal. Pays cold-start every time; keeps the RPC chain. Wins on isolation (handler crashes don't touch the user's session) and lets the handler run with no live Neovim — but the bash version's "degrade safely without nvim" path was always doing nothing useful, so the second win is illusory.
+- **B — In-process Lua via one RPC** *(chosen)*. Per-agent hook entry makes a single `nvim --server <socket> --remote-expr 'luaeval(...)'` call into the running Neovim. No cold-start, no intra-handler RPC chatter.
+
+Windows portability — the original motivation for #47 — is satisfied identically by both options. The orchestration logic (the prize of #47) is Lua either way; the only per-OS surface is the thin per-agent hook entry, which needs a `.cmd`/`.ps1` shim on Windows regardless of A vs B.
+
+## Consequences
+
+- The pre-tool pipeline runs on Neovim's main thread. None of the work is CPU-heavy (regex scans of Bash commands, JSON decode, file copies), but a 20-file MultiEdit or ApplyPatch does it all serially during the hook. Acceptable; if it ever bites, individual stages can be deferred with `vim.schedule`.
+- If the user's Neovim is unreachable (no nvim running, stale socket, RPC timeout, wrong-cwd instance), the hook exits 0 with no stdout — the plugin **abstains**, and the agent falls back to its native permission/edit flow exactly as if the plugin weren't installed. This preserves the bash version's "no-nvim degradation" path. The plugin enhances when it can; it does not gatekeep when it can't. Hard-failing on unreachable nvim was considered and rejected: a user who tabs away from or quits Neovim mid-session must not get a blocked or frozen agent.
+- [Hook context query](../../CONTEXT.md#hook-context-query) becomes a local function call inside `pre_tool.lua`; the RPC entry point survives only for callers that still live outside the user's Neovim (e.g. a backend that hasn't yet flipped to the Lua entry).
+- The `apply-edit` / `apply-multi-edit` / `apply-patch` logic moves to `lua/code-preview/apply/{edit,multi_edit,patch}.lua` and is called in-process from `pre_tool.lua`. The `bin/apply-*.lua` files survive as thin shims that `require` the module and forward CLI args, so any external caller invoking the old paths still works. Inlining preserves the cold-start win for the common Edit / MultiEdit / ApplyPatch proposals — leaving them as headless workers would have reintroduced the per-proposal spawn cost the in-process choice was made to eliminate.
+- The `bin/` directory's role narrows to thin shims and any genuinely out-of-process tooling. New orchestration and transformation code belongs under `lua/code-preview/`.
diff --git a/lua/code-preview/apply/edit.lua b/lua/code-preview/apply/edit.lua
new file mode 100644
index 0000000..cc3661b
--- /dev/null
+++ b/lua/code-preview/apply/edit.lua
@@ -0,0 +1,51 @@
+-- apply/edit.lua — Apply a single Edit (old_string → new_string) to a file.
+--
+-- Pure function: reads the file, applies a literal (non-pattern) replacement,
+-- returns the resulting content as a string. Empty old_string is treated as
+-- "prepend new_string" to match the historical bin/apply-edit.lua behaviour.
+
+local M = {}
+
+--- @param file_path string  absolute path to the file (may not exist)
+--- @param old_string string  literal text to find
+--- @param new_string string  literal replacement text
+--- @param replace_all boolean  if true, replace every occurrence
+--- @return string  the resulting file content
+function M.apply(file_path, old_string, new_string, replace_all)
+  local content = ""
+  local fh = io.open(file_path, "r")
+  if fh then
+    content = fh:read("*a")
+    fh:close()
+  end
+
+  if replace_all then
+    if old_string == "" then
+      return new_string .. content
+    end
+    local parts = {}
+    local search_start = 1
+    while true do
+      local s, e = string.find(content, old_string, search_start, true)
+      if not s then
+        table.insert(parts, content:sub(search_start))
+        break
+      end
+      table.insert(parts, content:sub(search_start, s - 1))
+      table.insert(parts, new_string)
+      search_start = e + 1
+    end
+    return table.concat(parts)
+  else
+    if old_string == "" then
+      return new_string .. content
+    end
+    local s, e = string.find(content, old_string, 1, true)
+    if s then
+      return content:sub(1, s - 1) .. new_string .. content:sub(e + 1)
+    end
+    return content
+  end
+end
+
+return M
diff --git a/lua/code-preview/apply/multi_edit.lua b/lua/code-preview/apply/multi_edit.lua
new file mode 100644
index 0000000..5ab8bd0
--- /dev/null
+++ b/lua/code-preview/apply/multi_edit.lua
@@ -0,0 +1,36 @@
+-- apply/multi_edit.lua — Apply a MultiEdit (sequential edits) to a file.
+--
+-- Pure function: reads the file, applies each edit in order with literal
+-- (non-pattern) replacement, returns the resulting content as a string.
+-- Edits that don't match are skipped silently (matches historical behaviour).
+
+local M = {}
+
+--- @param file_path string  absolute path to the file (may not exist)
+--- @param edits table  list of {old_string, new_string}
+--- @return string  the resulting file content
+function M.apply(file_path, edits)
+  local content = ""
+  local fh = io.open(file_path, "r")
+  if fh then
+    content = fh:read("*a")
+    fh:close()
+  end
+
+  for _, edit in ipairs(edits or {}) do
+    local old = edit.old_string or ""
+    local new = edit.new_string or ""
+    if old == "" then
+      content = new .. content
+    else
+      local s, e = string.find(content, old, 1, true)
+      if s then
+        content = content:sub(1, s - 1) .. new .. content:sub(e + 1)
+      end
+    end
+  end
+
+  return content
+end
+
+return M
diff --git a/lua/code-preview/apply/patch.lua b/lua/code-preview/apply/patch.lua
new file mode 100644
index 0000000..3b1b687
--- /dev/null
+++ b/lua/code-preview/apply/patch.lua
@@ -0,0 +1,191 @@
+-- apply/patch.lua — Parse OpenCode/GPT-style patch format and produce
+-- per-file original/proposed line lists.
+--
+-- The patch shape:
+--
+--   *** Begin Patch
+--   *** Update File: path/to/file
+--   @@
+--   -old line
+--   +new line
+--    context line
+--   *** End Patch
+--
+-- (Plus *** Add File: and *** Delete File: variants.)
+--
+-- Pure function: returns a list of {path, rel_path, action, orig, prop} where
+-- orig and prop are arrays of lines. The caller decides whether to write them
+-- to files (the bin/apply-patch.lua shim does, pre_tool may use them
+-- differently in future).
+
+local M = {}
+
+local function resolve_path(path, cwd)
+  if path:sub(1, 1) == "/" then
+    return path
+  end
+  return cwd .. "/" .. path
+end
+
+local function read_lines(path)
+  local fh = io.open(path, "r")
+  if not fh then
+    return {}
+  end
+  local lines = {}
+  for line in fh:lines() do
+    table.insert(lines, line)
+  end
+  fh:close()
+  return lines
+end
+
+local function apply_hunks(orig_lines, hunks)
+  if #hunks == 0 then
+    return orig_lines
+  end
+
+  local result = {}
+  local orig_idx = 1
+
+  for _, hunk in ipairs(hunks) do
+    local match_lines = {}
+    for _, hl in ipairs(hunk.lines) do
+      local prefix = hl:sub(1, 1)
+      if prefix == " " then
+        table.insert(match_lines, { type = "context", text = hl:sub(2) })
+      elseif prefix == "-" then
+        table.insert(match_lines, { type = "remove", text = hl:sub(2) })
+      elseif prefix == "+" then
+        table.insert(match_lines, { type = "add", text = hl:sub(2) })
+      else
+        table.insert(match_lines, { type = "context", text = hl })
+      end
+    end
+
+    local first_match_text = nil
+    for _, ml in ipairs(match_lines) do
+      if ml.type == "context" or ml.type == "remove" then
+        first_match_text = ml.text
+        break
+      end
+    end
+
+    if first_match_text then
+      while orig_idx <= #orig_lines do
+        if orig_lines[orig_idx] == first_match_text then
+          break
+        end
+        table.insert(result, orig_lines[orig_idx])
+        orig_idx = orig_idx + 1
+      end
+    end
+
+    for _, ml in ipairs(match_lines) do
+      if ml.type == "context" then
+        table.insert(result, ml.text)
+        orig_idx = orig_idx + 1
+      elseif ml.type == "remove" then
+        orig_idx = orig_idx + 1
+      elseif ml.type == "add" then
+        table.insert(result, ml.text)
+      end
+    end
+  end
+
+  while orig_idx <= #orig_lines do
+    table.insert(result, orig_lines[orig_idx])
+    orig_idx = orig_idx + 1
+  end
+
+  return result
+end
+
+local function parse_sections(patch_text)
+  local files = {}
+  local current_file = nil
+  local current_action = nil
+
+  for line in (patch_text .. "\n"):gmatch("([^\n]*)\n") do
+    local update_path = line:match("^%*%*%* Update File:%s*(.+)$")
+    local add_path = line:match("^%*%*%* Add File:%s*(.+)$")
+    local delete_path = line:match("^%*%*%* Delete File:%s*(.+)$")
+
+    if update_path then
+      current_file = { path = update_path:gsub("%s+$", ""), action = "update", hunks = {}, current_hunk = nil }
+      table.insert(files, current_file)
+      current_action = "update"
+    elseif add_path then
+      current_file = { path = add_path:gsub("%s+$", ""), action = "add", hunks = {}, current_hunk = nil }
+      table.insert(files, current_file)
+      current_action = "add"
+    elseif delete_path then
+      current_file = { path = delete_path:gsub("%s+$", ""), action = "delete", hunks = {}, current_hunk = nil }
+      table.insert(files, current_file)
+      current_action = "delete"
+    elseif line:match("^@@") and current_file then
+      current_file.current_hunk = { lines = {} }
+      table.insert(current_file.hunks, current_file.current_hunk)
+    elseif line == "*** End Patch" or line == "*** Begin Patch" then
+      current_file = nil
+    elseif current_file then
+      -- `*** Add File:` in the GPT patch format has no `@@` marker — lazy-
+      -- create a hunk on first content line so those lines aren't dropped.
+      if not current_file.current_hunk and current_action == "add" then
+        current_file.current_hunk = { lines = {} }
+        table.insert(current_file.hunks, current_file.current_hunk)
+      end
+      if current_file.current_hunk then
+        table.insert(current_file.current_hunk.lines, line)
+      end
+    end
+  end
+
+  return files
+end
+
+--- @param patch_text string  the raw patch text
+--- @param cwd string  cwd used to resolve relative paths
+--- @return table  list of {path, rel_path, action, orig, prop} where
+---                orig and prop are arrays of lines
+function M.parse(patch_text, cwd)
+  local files = parse_sections(patch_text)
+  local results = {}
+
+  for _, file_section in ipairs(files) do
+    local abs_path = resolve_path(file_section.path, cwd)
+    local orig_lines, prop_lines
+
+    if file_section.action == "delete" then
+      orig_lines = read_lines(abs_path)
+      prop_lines = {}
+    elseif file_section.action == "add" then
+      orig_lines = {}
+      prop_lines = {}
+      for _, hunk in ipairs(file_section.hunks) do
+        for _, hl in ipairs(hunk.lines) do
+          if hl:sub(1, 1) == "+" then
+            table.insert(prop_lines, hl:sub(2))
+          elseif hl:sub(1, 1) ~= "-" then
+            table.insert(prop_lines, hl)
+          end
+        end
+      end
+    else
+      orig_lines = read_lines(abs_path)
+      prop_lines = apply_hunks(orig_lines, file_section.hunks)
+    end
+
+    table.insert(results, {
+      path = abs_path,
+      rel_path = file_section.path,
+      action = file_section.action,
+      orig = orig_lines,
+      prop = prop_lines,
+    })
+  end
+
+  return results
+end
+
+return M
diff --git a/lua/code-preview/post_tool.lua b/lua/code-preview/post_tool.lua
new file mode 100644
index 0000000..f5e8868
--- /dev/null
+++ b/lua/code-preview/post_tool.lua
@@ -0,0 +1,89 @@
+-- post_tool.lua — In-process orchestration for PostToolUse hooks.
+--
+-- Replaces bin/core-post-tool.sh (which remains alive for not-yet-flipped
+-- backends). The hook-entry shim passes the raw decoded hook JSON plus the
+-- backend name; handle() clears the relevant changes, closes the matching
+-- preview(s), and refreshes neo-tree.
+--
+-- Tempfile cleanup is delegated to the OS (/tmp eviction); we do not rm the
+-- per-proposal tempfiles here. The bash version did, but it was best-effort
+-- and survived restarts via wildcard sweep — relying on /tmp hygiene is
+-- equally fine and removes a class of "did I race the next hook?" bugs.
+
+local M = {}
+
+local normalisers = require("code-preview.pre_tool.normalisers")
+local changes     = require("code-preview.changes")
+local neo_tree    = require("code-preview.neo_tree")
+local diff        = require("code-preview.diff")
+local log         = require("code-preview.log")
+
+-- Extract paths from both unified-diff (+++ lines) and custom-patch
+-- (*** Update/Add/Delete File:) formats.
+local function patch_paths(patch_text, cwd)
+  local paths = {}
+  for line in (patch_text .. "\n"):gmatch("([^\n]*)\n") do
+    local plus = line:match("^%+%+%+ (.+)$")
+    if plus then
+      plus = plus:gsub("^b/", "")
+      if plus ~= "/dev/null" then
+        table.insert(paths, plus)
+      end
+    end
+    local custom = line:match("^%*%*%* %a+ File:%s*(.+)$")
+    if custom then
+      table.insert(paths, custom:gsub("%s+$", ""))
+    end
+  end
+  -- Resolve relative paths against cwd.
+  local out = {}
+  for _, p in ipairs(paths) do
+    if p:sub(1, 1) ~= "/" and cwd and cwd ~= "" then
+      table.insert(out, cwd .. "/" .. p)
+    else
+      table.insert(out, p)
+    end
+  end
+  return out
+end
+
+--- Handle a normalised PostToolUse hook.
+--- @param raw table  decoded hook payload (per-backend shape)
+--- @param backend string  CODE_PREVIEW_BACKEND value
+--- @return string  always empty — post-tool produces no stdout for any backend
+function M.handle(raw, backend)
+  local input = normalisers.normalise(raw, backend)
+  local tool_name = input and input.tool_name
+
+  log.info(log.fmt("post_tool: tool=%s backend=%s", tostring(tool_name), tostring(backend)))
+
+  if tool_name == "Bash" then
+    -- Bash pre-hook set deleted / bash_* markers without opening a preview.
+    -- Clear those statuses specifically so we don't clobber `modified` markers
+    -- from concurrent Edit/Write/ApplyPatch whose post-hook hasn't fired.
+    changes.clear_by_statuses({ "deleted", "bash_modified", "bash_created" })
+    neo_tree.refresh_deferred(200)
+    return ""
+  end
+
+  if tool_name == "ApplyPatch" then
+    local patch_text = input.tool_input and input.tool_input.patch_text
+    if patch_text and patch_text ~= "" then
+      for _, fpath in ipairs(patch_paths(patch_text, input.cwd or "")) do
+        log.info(log.fmt("post_tool: close patch file=%s", fpath))
+        diff.close_for_file(fpath)
+      end
+    end
+    return ""
+  end
+
+  local file_path = input.tool_input and input.tool_input.file_path
+  if file_path and file_path ~= "" then
+    log.info(log.fmt("post_tool: close file=%s", file_path))
+    diff.close_for_file(file_path)
+  end
+
+  return ""
+end
+
+return M
diff --git a/lua/code-preview/pre_tool/bash_detect.lua b/lua/code-preview/pre_tool/bash_detect.lua
new file mode 100644
index 0000000..d096edd
--- /dev/null
+++ b/lua/code-preview/pre_tool/bash_detect.lua
@@ -0,0 +1,254 @@
+-- pre_tool/bash_detect.lua — Tier 1 shell-write + rm detection.
+--
+-- Inputs: a Bash command string and the project cwd.
+-- Output: a structured table { rm_paths = {...}, write_paths = {...} }.
+--
+-- This is a port of the regex-based detection that lived inline in
+-- bin/core-pre-tool.sh. The edge cases here all come from real bugs; resist
+-- "obvious simplifications" without first reading bash_detect_spec.lua.
+
+local M = {}
+
+-- Resolve a raw token (possibly relative, possibly ~-prefixed) to an absolute
+-- path. Caller is responsible for unquoting first.
+local function resolve(p, cwd)
+  if p == "" then return nil end
+  if p:sub(1, 1) == "/" then return p end
+  if p == "~" then return os.getenv("HOME") or "~" end
+  if p:sub(1, 2) == "~/" then
+    return (os.getenv("HOME") or "~") .. "/" .. p:sub(3)
+  end
+  return cwd .. "/" .. p
+end
+
+-- Strip a single matching pair of surrounding quotes.
+local function unquote(s)
+  if #s >= 2 then
+    local first, last = s:sub(1, 1), s:sub(-1)
+    if (first == '"' and last == '"') or (first == "'" and last == "'") then
+      return s:sub(2, -2)
+    end
+  end
+  return s
+end
+
+-- Undo shell backslash-escapes that bash actually requires for filenames:
+-- \', \", \\, \ , \$, \&. Pseudo-escapes like \n / \t are NOT touched —
+-- those typically appear inside quoted strings (e.g. `printf '<!-- -->\n\n'`)
+-- and undoing them here would turn the leak into a fake-looking path.
+local SHELL_ESCAPED = { ["'"]=true, ['"']=true, ["\\"]=true, [" "]=true, ["$"]=true, ["&"]=true }
+local function shell_unescape(s)
+  return (s:gsub("\\(.)", function(c) return SHELL_ESCAPED[c] and c or ("\\" .. c) end))
+end
+
+-- True if the string looks like a transient file we should skip.
+local function is_transient(p)
+  if p:match("%.tmp$") or p:match("%.bak$") or p:match("%.swp$") then return true end
+  if p:sub(-1) == "~" then return true end
+  if p:sub(1, 5) == "/dev/" then return true end
+  return false
+end
+
+-- Reject obvious non-paths (leaked escape sequences, stray quotes, etc.).
+-- This catches cases like `printf '<!-- note -->\n\n'` where the regex picks
+-- up `\n\n'` from inside a quoted string.
+local function looks_like_path(p)
+  if p == "" then return false end
+  -- Reject backslash and double-quote: those typically leak from inside
+  -- quoted strings (e.g. `printf '<!-- -->\n\n'`). Apostrophe is allowed
+  -- because shell_unescape produces it legitimately from `\'`.
+  if p:find('[\\"]') then return false end
+  local first = p:sub(1, 1)
+  if first == "/" then return true end
+  if p:sub(1, 2) == "./" or p:sub(1, 3) == "../" then return true end
+  if p:sub(1, 2) == "~/" then return true end
+  if first:match("[%w_]") then return true end
+  return false
+end
+
+-- ── rm detection ─────────────────────────────────────────────────
+
+-- Iterate sub-commands separated by ; && || (single or double).
+local function each_subcommand(cmd)
+  local parts = {}
+  local buf = {}
+  local i = 1
+  while i <= #cmd do
+    local c = cmd:sub(i, i)
+    local n = cmd:sub(i + 1, i + 1)
+    if c == ";" then
+      table.insert(parts, table.concat(buf)); buf = {}; i = i + 1
+    elseif (c == "&" and n == "&") or (c == "|" and n == "|") then
+      table.insert(parts, table.concat(buf)); buf = {}; i = i + 2
+    elseif c == "&" or c == "|" then
+      table.insert(parts, table.concat(buf)); buf = {}; i = i + 1
+    else
+      table.insert(buf, c); i = i + 1
+    end
+  end
+  if #buf > 0 then table.insert(parts, table.concat(buf)) end
+  return parts
+end
+
+local function detect_rm_in(subcmd, cwd)
+  local cmd = subcmd:gsub("^%s+", "")
+  -- Optional `sudo `, then `rm` as standalone command.
+  local body = cmd:match("^sudo%s+rm%s+(.*)$") or cmd:match("^rm%s+(.*)$")
+  if not body then return {} end
+
+  local paths = {}
+  for token in body:gmatch("%S+") do
+    -- Skip flags (-rf, --force, etc.). Single-dash followed by alpha; or `--`.
+    if not token:match("^%-") then
+      local p = shell_unescape(unquote(token))
+      -- Strip trailing CR (Windows-style payloads).
+      p = p:gsub("\r$", "")
+      if p ~= "" then
+        local abs = resolve(p, cwd)
+        if abs then table.insert(paths, abs) end
+      end
+    end
+  end
+  return paths
+end
+
+function M.detect_rm_paths(cmd, cwd)
+  local out = {}
+  local seen = {}
+  for _, sub in ipairs(each_subcommand(cmd)) do
+    for _, p in ipairs(detect_rm_in(sub, cwd)) do
+      if not seen[p] then
+        seen[p] = true
+        table.insert(out, p)
+      end
+    end
+  end
+  return out
+end
+
+-- ── write-path detection ────────────────────────────────────────
+
+-- Match output redirections (`>`, `>>`, `&>`, `&>>`) and capture the filename.
+-- Excludes FD redirections (`2>&1`) by requiring no digit prefix on bare `>`.
+local function detect_redirects(cmd)
+  local out = {}
+  -- Walk character by character so we can disambiguate `2>&1` (skip) from
+  -- `> file` (capture). Cheap and explicit beats a clever regex here.
+  local i = 1
+  while i <= #cmd do
+    local c = cmd:sub(i, i)
+    local prev = i > 1 and cmd:sub(i - 1, i - 1) or ""
+    if c == ">" then
+      -- Skip if prev is digit (FD redirection like 2>) — unless prev is &.
+      if prev:match("%d") then
+        i = i + 1
+      else
+        -- Skip ">>" doubling
+        if cmd:sub(i + 1, i + 1) == ">" then i = i + 1 end
+        i = i + 1
+        -- Skip whitespace
+        while i <= #cmd and cmd:sub(i, i):match("%s") do i = i + 1 end
+        -- Collect token until terminator. Special: `>&1` etc. emit empty.
+        if cmd:sub(i, i) == "&" then
+          -- It's an FD dup like `>&1`; skip the dup target.
+          i = i + 1
+          while i <= #cmd and cmd:sub(i, i):match("[%w_]") do i = i + 1 end
+        else
+          local start = i
+          while i <= #cmd do
+            local ch = cmd:sub(i, i)
+            if ch:match("[%s&;|<>(){}`]") then break end
+            i = i + 1
+          end
+          if i > start then
+            local tok = cmd:sub(start, i - 1)
+            if tok ~= "" and not tok:match("^/dev/(null|stdout|stderr|tty)$") then
+              table.insert(out, tok)
+            end
+          end
+        end
+      end
+    else
+      i = i + 1
+    end
+  end
+  return out
+end
+
+-- `mv SRC DST` / `cp SRC DST` — emit DST. Greedy last token; misses quoted
+-- paths with spaces and the GNU `-t DST SRC...` flag (acceptable for Tier 1).
+local function detect_mv_cp(cmd)
+  local out = {}
+  for _, sub in ipairs(each_subcommand(cmd)) do
+    local body = sub:match("^%s*mv%s+(.+)$") or sub:match("^%s*cp%s+(.+)$")
+    if body then
+      local tokens = {}
+      for tok in body:gmatch("%S+") do table.insert(tokens, tok) end
+      if #tokens > 0 then table.insert(out, tokens[#tokens]) end
+    end
+  end
+  return out
+end
+
+-- `tee [-a] FILE` — captures only the first target.
+local function detect_tee(cmd)
+  local out = {}
+  -- Match "tee" optionally followed by "-a", then the next token.
+  local body = cmd:match("tee%s+%-a%s+([^%s&;|<>(){}`]+)")
+  if body then
+    table.insert(out, body)
+  else
+    body = cmd:match("tee%s+([^%s&;|<>(){}`]+)")
+    if body and body ~= "-a" then table.insert(out, body) end
+  end
+  return out
+end
+
+-- `sed -i ... FILE` — last token wins; BSD's backup-suffix would be flagged
+-- too (acceptable for Tier 1).
+local function detect_sed_i(cmd)
+  local out = {}
+  -- Match `sed` then a flag-token containing `i`, then capture trailing args
+  -- up to the next pipe/semicolon.
+  for body in cmd:gmatch("sed%s+%-[%a]*i[%a]*%s+([^|&;]+)") do
+    local tokens = {}
+    for tok in body:gmatch("%S+") do table.insert(tokens, tok) end
+    if #tokens > 0 then table.insert(out, tokens[#tokens]) end
+  end
+  return out
+end
+
+function M.detect_write_paths(cmd, cwd)
+  local raw = {}
+  for _, p in ipairs(detect_redirects(cmd)) do table.insert(raw, p) end
+  for _, p in ipairs(detect_mv_cp(cmd))     do table.insert(raw, p) end
+  for _, p in ipairs(detect_tee(cmd))       do table.insert(raw, p) end
+  for _, p in ipairs(detect_sed_i(cmd))     do table.insert(raw, p) end
+
+  local out = {}
+  local seen = {}
+  for _, r in ipairs(raw) do
+    local p = shell_unescape(unquote(r))
+    if looks_like_path(p) then
+      local abs = resolve(p, cwd)
+      if abs and not is_transient(abs) and not seen[abs] then
+        seen[abs] = true
+        table.insert(out, abs)
+      end
+    end
+  end
+  return out
+end
+
+--- Combined entry point used by pre_tool.handle for Bash proposals.
+--- @param cmd string  the raw Bash command
+--- @param cwd string  project cwd for relative-path resolution
+--- @return table  { rm_paths = {...absolute...}, write_paths = {...absolute...} }
+function M.detect(cmd, cwd)
+  return {
+    rm_paths    = M.detect_rm_paths(cmd, cwd),
+    write_paths = M.detect_write_paths(cmd, cwd),
+  }
+end
+
+return M
diff --git a/lua/code-preview/pre_tool/emitters.lua b/lua/code-preview/pre_tool/emitters.lua
new file mode 100644
index 0000000..55ffadb
--- /dev/null
+++ b/lua/code-preview/pre_tool/emitters.lua
@@ -0,0 +1,43 @@
+-- pre_tool/emitters.lua — Per-backend stdout shape produced by handle().
+--
+-- The hook-entry shim prints whatever string handle() returns. For most
+-- backends that's empty (the hook is a side effect, not a permission gate).
+-- For Claude Code the plugin actively emits a permissionDecision JSON envelope
+-- so the agent prompts the user before writing — unless the user has set
+-- diff.defer_claude_permissions, in which case we abstain and let Claude
+-- Code's own permission settings win.
+
+local M = {}
+
+local function none(_ctx)
+  return ""
+end
+
+local function claudecode(ctx)
+  if ctx.has_nvim == false then return "" end
+  if ctx.defer_claude_permissions then return "" end
+  local reason = "Diff preview sent to Neovim. Review before accepting."
+  return vim.json.encode({
+    hookSpecificOutput = {
+      hookEventName = "PreToolUse",
+      permissionDecision = "ask",
+      permissionDecisionReason = reason,
+    },
+  }) .. "\n"
+end
+
+M.emitters = {
+  claudecode = claudecode,
+  opencode   = none,
+  -- codex / copilot / gemini default to `none` via the fallback below.
+}
+
+--- @param backend string
+--- @param ctx table  { has_nvim, defer_claude_permissions, ... }
+--- @return string  bytes to print to stdout from the hook-entry shim
+function M.emit(backend, ctx)
+  local fn = M.emitters[backend] or none
+  return fn(ctx)
+end
+
+return M
diff --git a/lua/code-preview/pre_tool/init.lua b/lua/code-preview/pre_tool/init.lua
new file mode 100644
index 0000000..55933ad
--- /dev/null
+++ b/lua/code-preview/pre_tool/init.lua
@@ -0,0 +1,251 @@
+-- pre_tool/init.lua — In-process orchestration for PreToolUse hooks.
+--
+-- Replaces bin/core-pre-tool.sh (which remains alive for not-yet-flipped
+-- backends until issue #47 phase 3 finishes for all of them). The per-OS
+-- hook-entry shim passes the raw decoded hook JSON plus the backend name;
+-- handle() does normalisation, tool dispatch, side effects (changes registry,
+-- neo-tree refresh, diff.show_diff), and returns the per-backend stdout bytes.
+--
+-- See docs/adr/0005-core-handler-runs-in-process.md.
+
+local M = {}
+
+local normalisers = require("code-preview.pre_tool.normalisers")
+local emitters    = require("code-preview.pre_tool.emitters")
+local bash_detect = require("code-preview.pre_tool.bash_detect")
+
+local apply_edit       = require("code-preview.apply.edit")
+local apply_multi_edit = require("code-preview.apply.multi_edit")
+local apply_patch      = require("code-preview.apply.patch")
+
+local changes  = require("code-preview.changes")
+local neo_tree = require("code-preview.neo_tree")
+local diff     = require("code-preview.diff")
+local log      = require("code-preview.log")
+
+-- ── Tempfile helpers ─────────────────────────────────────────────
+-- Bash used $$ to namespace /tmp/claude-diff-*. In-process Lua uses hrtime +
+-- a monotonic counter so multiple proposals in the same Neovim never collide.
+
+local _counter = 0
+local function next_id()
+  _counter = _counter + 1
+  return string.format("%d-%d", vim.loop.hrtime(), _counter)
+end
+
+local function tmpdir()
+  return os.getenv("TMPDIR") or "/tmp"
+end
+
+local function write_file(path, content)
+  local fh = assert(io.open(path, "w"))
+  fh:write(content or "")
+  fh:close()
+end
+
+local function copy_or_empty(src_path, dst_path)
+  local fh = io.open(src_path, "r")
+  if fh then
+    local content = fh:read("*a")
+    fh:close()
+    write_file(dst_path, content)
+  else
+    write_file(dst_path, "")
+  end
+end
+
+-- ── In-process hook context (replaces hook_context RPC) ──────────
+
+local function file_visible(file_path)
+  if not file_path or file_path == "" then return false end
+  local target = vim.uv.fs_realpath(file_path) or vim.fn.fnamemodify(file_path, ":p")
+  for _, w in ipairs(vim.api.nvim_list_wins()) do
+    local b = vim.api.nvim_win_get_buf(w)
+    local raw = vim.api.nvim_buf_get_name(b)
+    if raw ~= "" then
+      local name = vim.uv.fs_realpath(raw) or vim.fn.fnamemodify(raw, ":p")
+      if name == target then return true end
+    end
+  end
+  return false
+end
+
+local function should_show(cfg, file_path)
+  if not (cfg.diff and cfg.diff.visible_only) then return true end
+  return file_visible(file_path)
+end
+
+-- ── Per-tool handlers ───────────────────────────────────────────
+
+local function handle_edit(input, cfg)
+  local file_path = input.tool_input.file_path
+  local id = next_id()
+  local orig = tmpdir() .. "/claude-diff-original-" .. id
+  local prop = tmpdir() .. "/claude-diff-proposed-" .. id
+
+  copy_or_empty(file_path, orig)
+  local content = apply_edit.apply(
+    file_path,
+    input.tool_input.old_string or "",
+    input.tool_input.new_string or "",
+    input.tool_input.replace_all == true
+  )
+  write_file(prop, content)
+
+  if should_show(cfg, file_path) then
+    local display = file_path
+    if input.cwd and file_path:sub(1, #input.cwd + 1) == input.cwd .. "/" then
+      display = file_path:sub(#input.cwd + 2)
+    end
+    diff.show_diff(orig, prop, display, file_path, nil)
+  else
+    log.info(log.fmt("pre_tool: skipping diff for %s (visible_only)", file_path))
+  end
+end
+
+local function handle_write(input, cfg)
+  local file_path = input.tool_input.file_path
+  local id = next_id()
+  local orig = tmpdir() .. "/claude-diff-original-" .. id
+  local prop = tmpdir() .. "/claude-diff-proposed-" .. id
+
+  copy_or_empty(file_path, orig)
+  write_file(prop, input.tool_input.content or "")
+
+  if should_show(cfg, file_path) then
+    local display = file_path
+    if input.cwd and file_path:sub(1, #input.cwd + 1) == input.cwd .. "/" then
+      display = file_path:sub(#input.cwd + 2)
+    end
+    diff.show_diff(orig, prop, display, file_path, nil)
+  else
+    log.info(log.fmt("pre_tool: skipping diff for %s (visible_only)", file_path))
+  end
+end
+
+local function handle_multi_edit(input, cfg)
+  local file_path = input.tool_input.file_path
+  local id = next_id()
+  local orig = tmpdir() .. "/claude-diff-original-" .. id
+  local prop = tmpdir() .. "/claude-diff-proposed-" .. id
+
+  copy_or_empty(file_path, orig)
+  local content = apply_multi_edit.apply(file_path, input.tool_input.edits or {})
+  write_file(prop, content)
+
+  if should_show(cfg, file_path) then
+    local display = file_path
+    if input.cwd and file_path:sub(1, #input.cwd + 1) == input.cwd .. "/" then
+      display = file_path:sub(#input.cwd + 2)
+    end
+    diff.show_diff(orig, prop, display, file_path, nil)
+  else
+    log.info(log.fmt("pre_tool: skipping diff for %s (visible_only)", file_path))
+  end
+end
+
+local function handle_bash(input)
+  local cmd = input.tool_input.command or ""
+  local detected = bash_detect.detect(cmd, input.cwd or "")
+
+  local touched = false
+
+  -- rm first (rm wins for reveal precedence).
+  for _, p in ipairs(detected.rm_paths) do
+    changes.set(p, "deleted")
+    touched = true
+  end
+
+  for _, p in ipairs(detected.write_paths) do
+    local status = vim.uv.fs_stat(p) and "bash_modified" or "bash_created"
+    changes.set(p, status)
+    touched = true
+  end
+
+  if touched then
+    log.info(log.fmt("pre_tool: bash rm=%d write=%d",
+      #detected.rm_paths, #detected.write_paths))
+    neo_tree.refresh()
+    -- Reveal: rm beats write.
+    local target = detected.rm_paths[1] or detected.write_paths[1]
+    if target then
+      neo_tree.reveal_deferred(target, 300)
+    end
+  end
+end
+
+local function handle_apply_patch(input, cfg)
+  local patch_text = input.tool_input and input.tool_input.patch_text
+  if not patch_text or patch_text == "" then
+    log.info("pre_tool: ApplyPatch with empty patch_text")
+    return
+  end
+
+  local id = next_id()
+  local outdir = tmpdir() .. "/claude-patch-out-" .. id
+  vim.fn.mkdir(outdir, "p")
+
+  local files = apply_patch.parse(patch_text, input.cwd or "")
+
+  local function write_lines(path, lines)
+    local fh = assert(io.open(path, "w"))
+    for i, line in ipairs(lines) do
+      fh:write(line)
+      if i < #lines then fh:write("\n") end
+    end
+    if #lines > 0 then fh:write("\n") end
+    fh:close()
+  end
+
+  for i, file in ipairs(files) do
+    local tag = string.format("%02d", i)
+    local orig = outdir .. "/" .. tag .. "-orig"
+    local prop = outdir .. "/" .. tag .. "-prop"
+    write_lines(orig, file.orig)
+    write_lines(prop, file.prop)
+
+    if should_show(cfg, file.path) then
+      log.info(log.fmt("pre_tool: ApplyPatch send %s action=%s", file.rel_path, file.action))
+      diff.show_diff(orig, prop, file.rel_path, file.path, file.action)
+    else
+      log.info(log.fmt("pre_tool: ApplyPatch skip %s (visible_only)", file.rel_path))
+    end
+  end
+end
+
+local dispatchers = {
+  Edit       = handle_edit,
+  Write      = handle_write,
+  MultiEdit  = handle_multi_edit,
+  Bash       = function(input, _cfg) handle_bash(input) end,
+  ApplyPatch = handle_apply_patch,
+}
+
+-- ── Public entry ─────────────────────────────────────────────────
+
+--- Handle a normalised PreToolUse hook.
+--- @param raw table  decoded hook payload (per-backend shape)
+--- @param backend string  CODE_PREVIEW_BACKEND value
+--- @return string  bytes the hook-entry shim should print to stdout
+function M.handle(raw, backend)
+  local cfg = require("code-preview").config or {}
+  local input = normalisers.normalise(raw, backend)
+  local tool_name = input and input.tool_name
+
+  log.info(log.fmt("pre_tool: tool=%s backend=%s", tostring(tool_name), tostring(backend)))
+
+  local fn = dispatchers[tool_name]
+  if fn then
+    local ok, err = pcall(fn, input, cfg)
+    if not ok then
+      log.error("pre_tool: dispatch failed: " .. tostring(err))
+    end
+  end
+
+  return emitters.emit(backend, {
+    has_nvim = true,
+    defer_claude_permissions = cfg.diff and cfg.diff.defer_claude_permissions or false,
+  })
+end
+
+return M
diff --git a/lua/code-preview/pre_tool/normalisers.lua b/lua/code-preview/pre_tool/normalisers.lua
new file mode 100644
index 0000000..0ea4100
--- /dev/null
+++ b/lua/code-preview/pre_tool/normalisers.lua
@@ -0,0 +1,36 @@
+-- pre_tool/normalisers.lua — Per-backend hook payload normalisation.
+--
+-- Every backend passes the raw hook payload (parsed from JSON) and a backend
+-- name; the matching normaliser returns the canonical shape consumed by
+-- pre_tool.handle:
+--
+--   { tool_name = "Edit"|"Write"|"MultiEdit"|"Bash"|"ApplyPatch",
+--     cwd       = "/abs/path",
+--     tool_input = { file_path, ..., (tool-specific fields) } }
+--
+-- Today most backends pre-normalise on their own side (Claude Code's hook
+-- format is already canonical; OpenCode's TS plugin maps camelCase →
+-- snake_case before invoking us), so most entries here are identity. New
+-- backends slot in by adding a function to the table.
+
+local M = {}
+
+local function identity(raw)
+  return raw
+end
+
+M.normalisers = {
+  claudecode = identity,
+  opencode   = identity,
+  -- codex / copilot / gemini will land their own normalisers as they flip.
+}
+
+--- @param raw table  decoded hook payload
+--- @param backend string  CODE_PREVIEW_BACKEND value
+--- @return table  { tool_name, cwd, tool_input }
+function M.normalise(raw, backend)
+  local fn = M.normalisers[backend] or identity
+  return fn(raw)
+end
+
+return M
diff --git a/tests/plugin/pre_tool_bash_detect_spec.lua b/tests/plugin/pre_tool_bash_detect_spec.lua
new file mode 100644
index 0000000..21b2d30
--- /dev/null
+++ b/tests/plugin/pre_tool_bash_detect_spec.lua
@@ -0,0 +1,82 @@
+-- pre_tool_bash_detect_spec.lua — Tier 1 shell-write + rm detection.
+--
+-- Table-driven. Each row pins a documented edge case from the historical
+-- bin/core-pre-tool.sh detection logic. New rows go at the bottom with a
+-- short comment explaining the case. Resist "obvious simplifications" to
+-- bash_detect.lua without first reading these rows.
+
+local bash_detect = require("code-preview.pre_tool.bash_detect")
+
+local CWD = "/proj"
+local HOME = os.getenv("HOME") or "/root"
+
+local function sorted(t)
+  local copy = {}
+  for _, v in ipairs(t) do table.insert(copy, v) end
+  table.sort(copy)
+  return copy
+end
+
+describe("bash_detect.detect_rm_paths", function()
+  local cases = {
+    { name = "plain rm",                   cmd = "rm foo.txt",                  expect = { CWD .. "/foo.txt" } },
+    { name = "rm with flags",              cmd = "rm -rf build",                expect = { CWD .. "/build" } },
+    { name = "sudo rm absolute",           cmd = "sudo rm /etc/foo",            expect = { "/etc/foo" } },
+    { name = "rm with home tilde",         cmd = "rm ~/.config/x",              expect = { HOME .. "/.config/x" } },
+    { name = "apostrophe in filename",     cmd = "rm \"it's-mine.txt\"",        expect = { CWD .. "/it's-mine.txt" } },
+    { name = "compound with &&",           cmd = "rm a && rm b",                expect = { CWD .. "/a", CWD .. "/b" } },
+    { name = "compound with ;",            cmd = "rm a ; rm b",                 expect = { CWD .. "/a", CWD .. "/b" } },
+    { name = "/tmp not filtered for rm",   cmd = "rm /tmp/foo",                 expect = { "/tmp/foo" } },
+    { name = "trailing CR stripped",       cmd = "rm a.txt\r",                  expect = { CWD .. "/a.txt" } },
+    { name = "non-rm command ignored",     cmd = "echo rm foo",                 expect = {} },
+    -- Real-world case: Claude Code escapes apostrophes in unquoted filenames.
+    { name = "backslash-escaped apostrophe", cmd = "rm it\\'s-mine.txt",        expect = { CWD .. "/it's-mine.txt" } },
+    -- Backslash-escaped spaces (`rm my\ file.txt`) would need a real shell
+    -- tokeniser to split correctly; documented as a Tier 1 limitation.
+  }
+  for _, c in ipairs(cases) do
+    it(c.name, function()
+      assert.are.same(sorted(c.expect), sorted(bash_detect.detect_rm_paths(c.cmd, CWD)))
+    end)
+  end
+end)
+
+describe("bash_detect.detect_write_paths", function()
+  local cases = {
+    { name = "single > redirect",          cmd = "echo x > foo.txt",            expect = { CWD .. "/foo.txt" } },
+    { name = "append >> redirect",         cmd = "echo x >> log.txt",           expect = { CWD .. "/log.txt" } },
+    { name = "absolute redirect",          cmd = "echo x > /var/log/y",         expect = { "/var/log/y" } },
+    { name = "/tmp not filtered for writes", cmd = "echo x > /tmp/real",        expect = { "/tmp/real" } },
+    { name = "FD redirection 2>&1 skipped",cmd = "cmd 2>&1",                    expect = {} },
+    { name = "/dev/null filtered",         cmd = "cmd > /dev/null",             expect = {} },
+    { name = "/dev/stderr filtered",       cmd = "cmd > /dev/stderr",           expect = {} },
+    { name = "mv writes destination",      cmd = "mv a.tmp b",                  expect = { CWD .. "/b" } },
+    { name = "cp writes destination",      cmd = "cp a b",                      expect = { CWD .. "/b" } },
+    { name = "tee target",                 cmd = "echo x | tee foo.txt",        expect = { CWD .. "/foo.txt" } },
+    { name = "tee -a target",              cmd = "echo x | tee -a foo.txt",     expect = { CWD .. "/foo.txt" } },
+    { name = "sed -i target",              cmd = "sed -i 's/x/y/' foo.txt",     expect = { CWD .. "/foo.txt" } },
+    { name = "transient .tmp filtered",    cmd = "echo x > scratch.tmp",        expect = {} },
+    { name = "transient ~ filtered",       cmd = "echo x > foo~",               expect = {} },
+    { name = "home tilde expanded",        cmd = "echo x > ~/notes.md",         expect = { HOME .. "/notes.md" } },
+    -- The HTML-comment false positive: the redirect regex picks up the `>`
+    -- in `-->`, but looks_like_path rejects the resulting token because it
+    -- contains a backslash (leaked from inside a quoted string).
+    { name = "html comment false positive", cmd = "printf '<!-- note -->\\n\\n'", expect = {} },
+    { name = "dedup duplicates",           cmd = "echo a > x.txt && echo b > x.txt", expect = { CWD .. "/x.txt" } },
+    -- Apostrophe-escaped paths in redirects (companion to the rm case).
+    { name = "backslash-escaped apostrophe in redirect", cmd = "echo x > it\\'s.txt", expect = { CWD .. "/it's.txt" } },
+  }
+  for _, c in ipairs(cases) do
+    it(c.name, function()
+      assert.are.same(sorted(c.expect), sorted(bash_detect.detect_write_paths(c.cmd, CWD)))
+    end)
+  end
+end)
+
+describe("bash_detect.detect (combined)", function()
+  it("returns both rm and write paths", function()
+    local r = bash_detect.detect("rm old.txt && echo x > new.txt", CWD)
+    assert.are.same({ CWD .. "/old.txt" }, r.rm_paths)
+    assert.are.same({ CWD .. "/new.txt" }, r.write_paths)
+  end)
+end)
diff --git a/tests/plugin/pre_tool_handle_spec.lua b/tests/plugin/pre_tool_handle_spec.lua
new file mode 100644
index 0000000..2535dfe
--- /dev/null
+++ b/tests/plugin/pre_tool_handle_spec.lua
@@ -0,0 +1,87 @@
+-- pre_tool_handle_spec.lua — Smoke tests for the in-process orchestrator.
+--
+-- These exercise the happy paths and pin a few high-value invariants:
+--   - Bash proposals mutate the changes registry but never open previews
+--   - claudecode backend emits a permissionDecision JSON envelope
+--   - other backends emit empty stdout
+--   - unknown tool_name is a no-op (no crash)
+--
+-- Edit / Write / MultiEdit / ApplyPatch side effects bottom out in
+-- diff.show_diff, which we don't drive UI for in tests — we only assert that
+-- handle() does not raise.
+
+local pre_tool = require("code-preview.pre_tool")
+local changes  = require("code-preview.changes")
+
+local function payload(tool_name, tool_input, cwd)
+  return { tool_name = tool_name, cwd = cwd or "/proj", tool_input = tool_input }
+end
+
+describe("pre_tool.handle (Bash)", function()
+  before_each(function() changes.clear_all() end)
+
+  it("rm command marks file as deleted", function()
+    local p = "/proj/gone.txt"
+    pre_tool.handle(payload("Bash", { command = "rm gone.txt" }), "claudecode")
+    assert.equals("deleted", changes.get(p))
+  end)
+
+  it("redirect to new file marks bash_created", function()
+    local p = "/tmp/code-preview-test-" .. tostring(vim.loop.hrtime()) .. ".out"
+    pre_tool.handle(payload("Bash", { command = "echo x > " .. p }), "claudecode")
+    assert.equals("bash_created", changes.get(p))
+  end)
+
+  it("redirect to existing file marks bash_modified", function()
+    local p = "/tmp/code-preview-test-existing-" .. tostring(vim.loop.hrtime())
+    local fh = assert(io.open(p, "w")); fh:write("hi"); fh:close()
+    pre_tool.handle(payload("Bash", { command = "echo x > " .. p }), "claudecode")
+    assert.equals("bash_modified", changes.get(p))
+    os.remove(p)
+  end)
+
+  it("read-only command leaves registry empty", function()
+    pre_tool.handle(payload("Bash", { command = "ls -la" }), "claudecode")
+    assert.equals(0, vim.tbl_count(changes.get_all()))
+  end)
+
+  it("rm and write in one command both register", function()
+    pre_tool.handle(payload("Bash", { command = "rm old.txt && echo x > new.txt" }), "claudecode")
+    assert.equals("deleted",      changes.get("/proj/old.txt"))
+    assert.equals("bash_created", changes.get("/proj/new.txt"))
+  end)
+end)
+
+describe("pre_tool.handle (emitter output)", function()
+  it("claudecode emits permissionDecision JSON", function()
+    local out = pre_tool.handle(payload("Bash", { command = "ls" }), "claudecode")
+    assert.is_truthy(out:match("permissionDecision"))
+    assert.is_truthy(out:match("PreToolUse"))
+  end)
+
+  it("opencode emits empty stdout", function()
+    local out = pre_tool.handle(payload("Bash", { command = "ls" }), "opencode")
+    assert.equals("", out)
+  end)
+
+  it("unknown backend emits empty stdout", function()
+    local out = pre_tool.handle(payload("Bash", { command = "ls" }), "future-agent")
+    assert.equals("", out)
+  end)
+end)
+
+describe("pre_tool.handle (robustness)", function()
+  before_each(function() changes.clear_all() end)
+
+  it("unknown tool_name does not raise", function()
+    assert.has_no.errors(function()
+      pre_tool.handle(payload("UnknownTool", {}), "claudecode")
+    end)
+  end)
+
+  it("missing tool_input does not raise", function()
+    assert.has_no.errors(function()
+      pre_tool.handle({ tool_name = "Bash", cwd = "/proj" }, "claudecode")
+    end)
+  end)
+end)
diff --git a/tests/plugin/pre_tool_normaliser_spec.lua b/tests/plugin/pre_tool_normaliser_spec.lua
new file mode 100644
index 0000000..0c785f4
--- /dev/null
+++ b/tests/plugin/pre_tool_normaliser_spec.lua
@@ -0,0 +1,29 @@
+-- pre_tool_normaliser_spec.lua — Per-backend hook payload normalisation.
+--
+-- Today every supported backend pre-normalises on its own side (Claude Code's
+-- hook format is already canonical; OpenCode's TS plugin maps camelCase →
+-- snake_case before invoking us), so the entries here are identity. The
+-- value of this spec is locking the *contract* — a future backend that
+-- doesn't pre-normalise will add a non-identity entry and a row here.
+
+local normalisers = require("code-preview.pre_tool.normalisers")
+
+describe("normalisers.normalise", function()
+  local canonical = {
+    tool_name = "Edit",
+    cwd       = "/proj",
+    tool_input = { file_path = "/proj/foo.lua", old_string = "a", new_string = "b" },
+  }
+
+  it("claudecode is identity", function()
+    assert.are.same(canonical, normalisers.normalise(canonical, "claudecode"))
+  end)
+
+  it("opencode is identity (pre-normalised by TS plugin)", function()
+    assert.are.same(canonical, normalisers.normalise(canonical, "opencode"))
+  end)
+
+  it("unknown backend falls back to identity", function()
+    assert.are.same(canonical, normalisers.normalise(canonical, "future-agent"))
+  end)
+end)

From ef617dd9d120ff7ca78d9561b04e5c816eb1b0f8 Mon Sep 17 00:00:00 2001
From: Cannon07 <jayshitre@gmail.com>
Date: Tue, 19 May 2026 12:10:18 +0530
Subject: [PATCH 2/3] fix: emitter parity with bash core handler for CI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three CI failures, all rooted in subtle parity gaps between the new
in-process emitter and the bash core handler:

- vim.json.encode does not preserve table key order; Ubuntu's Lua hash
  seed produced a key order that broke the shell tests' byte-exact JSON
  comparison. Switched the claudecode emitter to a hand-built string
  matching the bash printf format exactly.

- Bash core exited 0 for Bash / ApplyPatch / unknown tools BEFORE
  reaching the permissionDecision printf. The new emitter was firing
  unconditionally. Restricted emission to Edit / Write / MultiEdit and
  threaded tool_name into the emitter context.

- test_stale_socket.sh asserted that the proposed temp file was written
  even when no Neovim was reachable — a side effect of the bash core
  always spawning apply-edit.lua. ADR-0005 deliberately removes that
  side effect (the plugin abstains entirely). Test updated to match
  the new contract.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 lua/code-preview/pre_tool/emitters.lua        | 20 +++++++++++--------
 lua/code-preview/pre_tool/init.lua            |  1 +
 .../backends/claudecode/test_stale_socket.sh  | 13 ++++++------
 tests/plugin/pre_tool_handle_spec.lua         | 20 +++++++++++++++----
 4 files changed, 36 insertions(+), 18 deletions(-)

diff --git a/lua/code-preview/pre_tool/emitters.lua b/lua/code-preview/pre_tool/emitters.lua
index 55ffadb..e90d49a 100644
--- a/lua/code-preview/pre_tool/emitters.lua
+++ b/lua/code-preview/pre_tool/emitters.lua
@@ -13,17 +13,21 @@ local function none(_ctx)
   return ""
 end
 
+-- Only Edit / Write / MultiEdit prompt for review under Claude Code. Bash,
+-- ApplyPatch, and unknown tools must produce no stdout (matches the bash
+-- core's `*) exit 0;;` / per-case early exits before the permission block).
+local CLAUDECODE_EMIT_TOOLS = { Edit = true, Write = true, MultiEdit = true }
+
 local function claudecode(ctx)
   if ctx.has_nvim == false then return "" end
   if ctx.defer_claude_permissions then return "" end
-  local reason = "Diff preview sent to Neovim. Review before accepting."
-  return vim.json.encode({
-    hookSpecificOutput = {
-      hookEventName = "PreToolUse",
-      permissionDecision = "ask",
-      permissionDecisionReason = reason,
-    },
-  }) .. "\n"
+  if not CLAUDECODE_EMIT_TOOLS[ctx.tool_name or ""] then return "" end
+  -- Hand-built JSON: vim.json.encode doesn't preserve table key order, so
+  -- the string varies across Lua hash seeds. The downstream consumer
+  -- (Claude Code) doesn't care about order, but the shell-level tests
+  -- assert byte-exact output. Keep the order matching the historical
+  -- bash printf format: hookEventName, permissionDecision, permissionDecisionReason.
+  return '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"Diff preview sent to Neovim. Review before accepting."}}\n'
 end
 
 M.emitters = {
diff --git a/lua/code-preview/pre_tool/init.lua b/lua/code-preview/pre_tool/init.lua
index 55933ad..cdc3541 100644
--- a/lua/code-preview/pre_tool/init.lua
+++ b/lua/code-preview/pre_tool/init.lua
@@ -244,6 +244,7 @@ function M.handle(raw, backend)
 
   return emitters.emit(backend, {
     has_nvim = true,
+    tool_name = tool_name,
     defer_claude_permissions = cfg.diff and cfg.diff.defer_claude_permissions or false,
   })
 end
diff --git a/tests/backends/claudecode/test_stale_socket.sh b/tests/backends/claudecode/test_stale_socket.sh
index f9d7db4..f5c4359 100644
--- a/tests/backends/claudecode/test_stale_socket.sh
+++ b/tests/backends/claudecode/test_stale_socket.sh
@@ -119,8 +119,7 @@ EOF
 )
 
   # Force scan mode by blanking any inherited NVIM_LISTEN_ADDRESS. The hook
-  # must still compute the proposed file and exit cleanly even if there is no
-  # project-specific Neovim to attach to.
+  # must exit cleanly when there is no project-specific Neovim to attach to.
   local exit_code=0
   echo "$payload" | \
     NVIM_LISTEN_ADDRESS= \
@@ -131,10 +130,12 @@ EOF
   # project-specific nvim instance.
   assert_eq "0" "$exit_code" "hook must exit 0 without a guaranteed project nvim match" || return 1
 
-  # The proposed temp file must exist (PID-suffixed): headless nvim computed the edit.
-  local proposed
-  proposed="$(ls -1t "$hook_tmpdir"/claude-diff-proposed-* 2>/dev/null | head -1)"
-  assert_file_exists "$proposed" "proposed file should be computed even without a project-specific nvim match" || return 1
+  # Per ADR-0005 (issue #47 phase 3), the hook abstains entirely when no
+  # Neovim is reachable: no proposed file is computed, no stdout, exit 0.
+  # The pre-phase-3 bash core also wrote a proposed temp file in this case
+  # as a side effect of spawning `nvim --headless -l apply-edit.lua`; we
+  # no longer do that. Claude Code falls back to its native flow as if the
+  # plugin weren't installed.
   rm -rf "$hook_tmpdir"
 }
 
diff --git a/tests/plugin/pre_tool_handle_spec.lua b/tests/plugin/pre_tool_handle_spec.lua
index 2535dfe..eced6dd 100644
--- a/tests/plugin/pre_tool_handle_spec.lua
+++ b/tests/plugin/pre_tool_handle_spec.lua
@@ -53,19 +53,31 @@ describe("pre_tool.handle (Bash)", function()
 end)
 
 describe("pre_tool.handle (emitter output)", function()
-  it("claudecode emits permissionDecision JSON", function()
-    local out = pre_tool.handle(payload("Bash", { command = "ls" }), "claudecode")
+  it("claudecode emits permissionDecision JSON for Edit", function()
+    local out = pre_tool.handle(
+      payload("Edit", { file_path = "/tmp/x", old_string = "a", new_string = "b" }),
+      "claudecode")
     assert.is_truthy(out:match("permissionDecision"))
     assert.is_truthy(out:match("PreToolUse"))
   end)
 
+  it("claudecode emits nothing for Bash", function()
+    local out = pre_tool.handle(payload("Bash", { command = "ls" }), "claudecode")
+    assert.equals("", out)
+  end)
+
+  it("claudecode emits nothing for unknown tool", function()
+    local out = pre_tool.handle(payload("Read", { file_path = "/tmp/x" }), "claudecode")
+    assert.equals("", out)
+  end)
+
   it("opencode emits empty stdout", function()
-    local out = pre_tool.handle(payload("Bash", { command = "ls" }), "opencode")
+    local out = pre_tool.handle(payload("Edit", { file_path = "/tmp/x" }), "opencode")
     assert.equals("", out)
   end)
 
   it("unknown backend emits empty stdout", function()
-    local out = pre_tool.handle(payload("Bash", { command = "ls" }), "future-agent")
+    local out = pre_tool.handle(payload("Edit", { file_path = "/tmp/x" }), "future-agent")
     assert.equals("", out)
   end)
 end)

From ed29b41689b0d4927baf08a5c619538fca48e4c0 Mon Sep 17 00:00:00 2001
From: Cannon07 <jayshitre@gmail.com>
Date: Tue, 19 May 2026 12:42:06 +0530
Subject: [PATCH 3/3] refactor: address review feedback for phase 3

Six small fixes surfaced in independent code review:

- pre_tool: extract present_single_file() helper from handle_edit /
  handle_write / handle_multi_edit (removed ~30 lines of duplication).
- pre_tool: add sweep_leftover_tempfiles(); call from setup() to clear
  stale /tmp/claude-diff-* across sessions (the bash post-tool did this
  via a global wildcard rm; per-proposal tracking deferred to follow-up).
- emitters: drop dead has_nvim branch (handle() always sets it true).
- claudecode shims: guard against malformed jq output, add comment
  explaining why `set -e` is intentionally omitted.
- post_tool: add post_tool_handle_spec.lua covering Bash status clear,
  concurrent-edit marker preservation, return-value contract, and
  robustness against malformed inputs.

Two review items deferred to a follow-up issue (per discussion):
  * Apply looks_like_path to rm tokens (behavioural change beyond bash
    parity).
  * Per-proposal tempfile tracking (the startup sweep covers the
    cross-session leak; within-session refinement comes later).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 backends/claudecode/code-close-diff.sh   |   5 +-
 backends/claudecode/code-preview-diff.sh |   8 +-
 lua/code-preview/init.lua                |   5 ++
 lua/code-preview/pre_tool/emitters.lua   |   1 -
 lua/code-preview/pre_tool/init.lua       | 102 ++++++++++++-----------
 tests/plugin/post_tool_handle_spec.lua   |  76 +++++++++++++++++
 6 files changed, 144 insertions(+), 53 deletions(-)
 create mode 100644 tests/plugin/post_tool_handle_spec.lua

diff --git a/backends/claudecode/code-close-diff.sh b/backends/claudecode/code-close-diff.sh
index beaf641..9862db8 100755
--- a/backends/claudecode/code-close-diff.sh
+++ b/backends/claudecode/code-close-diff.sh
@@ -8,6 +8,8 @@
 #
 # When Neovim is unreachable, the shim abstains silently (exit 0).
 
+# No `set -e`: abstain on jq/nvim_call failure rather than surfacing a
+# hook failure to the agent. See the matching note in code-preview-diff.sh.
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -23,5 +25,6 @@ if [[ -z "${NVIM_SOCKET:-}" ]]; then
   exit 0
 fi
 
-ARGS="$(jq -nc --argjson r "$INPUT" --arg b claudecode '[$r, $b]')"
+ARGS="$(jq -nc --argjson r "$INPUT" --arg b claudecode '[$r, $b]' 2>/dev/null || true)"
+[[ -z "$ARGS" ]] && exit 0
 nvim_call code-preview.post_tool handle "$ARGS" >/dev/null
diff --git a/backends/claudecode/code-preview-diff.sh b/backends/claudecode/code-preview-diff.sh
index 24cef88..562a604 100755
--- a/backends/claudecode/code-preview-diff.sh
+++ b/backends/claudecode/code-preview-diff.sh
@@ -11,6 +11,10 @@
 # Claude Code falls back to its native permission flow as if the plugin
 # weren't installed. See docs/adr/0005-core-handler-runs-in-process.md.
 
+# No `set -e`: the shim is the boundary between the agent and the plugin.
+# When jq fails on a malformed payload or nvim_call returns rc=2, we want
+# to exit 0 (abstain) so the agent falls back to its native flow rather
+# than seeing a hook failure.
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -27,5 +31,7 @@ if [[ -z "${NVIM_SOCKET:-}" ]]; then
   exit 0
 fi
 
-ARGS="$(jq -nc --argjson r "$INPUT" --arg b claudecode '[$r, $b]')"
+ARGS="$(jq -nc --argjson r "$INPUT" --arg b claudecode '[$r, $b]' 2>/dev/null || true)"
+# Malformed payload (jq couldn't parse) — abstain silently.
+[[ -z "$ARGS" ]] && exit 0
 nvim_call code-preview.pre_tool handle "$ARGS"
diff --git a/lua/code-preview/init.lua b/lua/code-preview/init.lua
index 00e4419..ac934fe 100644
--- a/lua/code-preview/init.lua
+++ b/lua/code-preview/init.lua
@@ -94,6 +94,11 @@ function M.setup(user_config)
   -- Self-register socket + cwd for hook-script discovery
   require("code-preview.pidfile").setup()
 
+  -- Clear any leftover /tmp/claude-diff-* tempfiles from prior sessions
+  -- (the in-process pre-tool flow has no global wildcard equivalent of the
+  -- old bash post-tool sweep — see pre_tool.sweep_leftover_tempfiles).
+  require("code-preview.pre_tool").sweep_leftover_tempfiles()
+
   -- ── New commands ──────────────────────────────────────────────
 
   vim.api.nvim_create_user_command("CodePreviewInstallClaudeCodeHooks", function()
diff --git a/lua/code-preview/pre_tool/emitters.lua b/lua/code-preview/pre_tool/emitters.lua
index e90d49a..6c076a7 100644
--- a/lua/code-preview/pre_tool/emitters.lua
+++ b/lua/code-preview/pre_tool/emitters.lua
@@ -19,7 +19,6 @@ end
 local CLAUDECODE_EMIT_TOOLS = { Edit = true, Write = true, MultiEdit = true }
 
 local function claudecode(ctx)
-  if ctx.has_nvim == false then return "" end
   if ctx.defer_claude_permissions then return "" end
   if not CLAUDECODE_EMIT_TOOLS[ctx.tool_name or ""] then return "" end
   -- Hand-built JSON: vim.json.encode doesn't preserve table key order, so
diff --git a/lua/code-preview/pre_tool/init.lua b/lua/code-preview/pre_tool/init.lua
index cdc3541..f5ff7b5 100644
--- a/lua/code-preview/pre_tool/init.lua
+++ b/lua/code-preview/pre_tool/init.lua
@@ -37,6 +37,30 @@ local function tmpdir()
   return os.getenv("TMPDIR") or "/tmp"
 end
 
+-- One-time startup sweep of leftover proposal tempfiles.
+--
+-- The bash post-tool ran `rm -f /tmp/claude-diff-original* /tmp/claude-diff-proposed*
+-- /tmp/claude-patch-*` after every PostToolUse hook — a global wildcard sweep.
+-- The new in-process flow doesn't have a natural hook to run that on every
+-- post-tool (and per-proposal tracking is a follow-up — see the parity-port
+-- hygiene issue). To prevent unbounded accumulation across long sessions
+-- where Neovim doesn't restart, run the sweep once at setup(). macOS doesn't
+-- auto-evict /tmp under a few days, so this matters in practice.
+function M.sweep_leftover_tempfiles()
+  local dir = tmpdir()
+  local fd = vim.loop.fs_scandir(dir)
+  if not fd then return end
+  while true do
+    local name = vim.loop.fs_scandir_next(fd)
+    if not name then break end
+    if name:match("^claude%-diff%-original%-") or
+       name:match("^claude%-diff%-proposed%-") or
+       name:match("^claude%-patch%-") then
+      pcall(vim.loop.fs_unlink, dir .. "/" .. name)
+    end
+  end
+end
+
 local function write_file(path, content)
   local fh = assert(io.open(path, "w"))
   fh:write(content or "")
@@ -77,71 +101,50 @@ end
 
 -- ── Per-tool handlers ───────────────────────────────────────────
 
-local function handle_edit(input, cfg)
-  local file_path = input.tool_input.file_path
+-- Compute the orig/proposed tempfile pair for a single-file tool and hand off
+-- to diff.show_diff (or skip when visible_only excludes the file). The only
+-- per-tool variation is how `proposed_content` is computed, so each handler
+-- below is a one-liner around this helper.
+local function present_single_file(file_path, proposed_content, input, cfg)
   local id = next_id()
   local orig = tmpdir() .. "/claude-diff-original-" .. id
   local prop = tmpdir() .. "/claude-diff-proposed-" .. id
 
   copy_or_empty(file_path, orig)
+  write_file(prop, proposed_content)
+
+  if not should_show(cfg, file_path) then
+    log.info(log.fmt("pre_tool: skipping diff for %s (visible_only)", file_path))
+    return
+  end
+
+  local display = file_path
+  if input.cwd and file_path:sub(1, #input.cwd + 1) == input.cwd .. "/" then
+    display = file_path:sub(#input.cwd + 2)
+  end
+  diff.show_diff(orig, prop, display, file_path, nil)
+end
+
+local function handle_edit(input, cfg)
+  local fp = input.tool_input.file_path
   local content = apply_edit.apply(
-    file_path,
+    fp,
     input.tool_input.old_string or "",
     input.tool_input.new_string or "",
     input.tool_input.replace_all == true
   )
-  write_file(prop, content)
-
-  if should_show(cfg, file_path) then
-    local display = file_path
-    if input.cwd and file_path:sub(1, #input.cwd + 1) == input.cwd .. "/" then
-      display = file_path:sub(#input.cwd + 2)
-    end
-    diff.show_diff(orig, prop, display, file_path, nil)
-  else
-    log.info(log.fmt("pre_tool: skipping diff for %s (visible_only)", file_path))
-  end
+  present_single_file(fp, content, input, cfg)
 end
 
 local function handle_write(input, cfg)
-  local file_path = input.tool_input.file_path
-  local id = next_id()
-  local orig = tmpdir() .. "/claude-diff-original-" .. id
-  local prop = tmpdir() .. "/claude-diff-proposed-" .. id
-
-  copy_or_empty(file_path, orig)
-  write_file(prop, input.tool_input.content or "")
-
-  if should_show(cfg, file_path) then
-    local display = file_path
-    if input.cwd and file_path:sub(1, #input.cwd + 1) == input.cwd .. "/" then
-      display = file_path:sub(#input.cwd + 2)
-    end
-    diff.show_diff(orig, prop, display, file_path, nil)
-  else
-    log.info(log.fmt("pre_tool: skipping diff for %s (visible_only)", file_path))
-  end
+  local fp = input.tool_input.file_path
+  present_single_file(fp, input.tool_input.content or "", input, cfg)
 end
 
 local function handle_multi_edit(input, cfg)
-  local file_path = input.tool_input.file_path
-  local id = next_id()
-  local orig = tmpdir() .. "/claude-diff-original-" .. id
-  local prop = tmpdir() .. "/claude-diff-proposed-" .. id
-
-  copy_or_empty(file_path, orig)
-  local content = apply_multi_edit.apply(file_path, input.tool_input.edits or {})
-  write_file(prop, content)
-
-  if should_show(cfg, file_path) then
-    local display = file_path
-    if input.cwd and file_path:sub(1, #input.cwd + 1) == input.cwd .. "/" then
-      display = file_path:sub(#input.cwd + 2)
-    end
-    diff.show_diff(orig, prop, display, file_path, nil)
-  else
-    log.info(log.fmt("pre_tool: skipping diff for %s (visible_only)", file_path))
-  end
+  local fp = input.tool_input.file_path
+  local content = apply_multi_edit.apply(fp, input.tool_input.edits or {})
+  present_single_file(fp, content, input, cfg)
 end
 
 local function handle_bash(input)
@@ -243,7 +246,6 @@ function M.handle(raw, backend)
   end
 
   return emitters.emit(backend, {
-    has_nvim = true,
     tool_name = tool_name,
     defer_claude_permissions = cfg.diff and cfg.diff.defer_claude_permissions or false,
   })
diff --git a/tests/plugin/post_tool_handle_spec.lua b/tests/plugin/post_tool_handle_spec.lua
new file mode 100644
index 0000000..b2db3af
--- /dev/null
+++ b/tests/plugin/post_tool_handle_spec.lua
@@ -0,0 +1,76 @@
+-- post_tool_handle_spec.lua — Smoke tests for the in-process post-tool.
+--
+-- post_tool.handle's contract:
+--   * Bash: clears `deleted` / `bash_modified` / `bash_created` markers from
+--     the changes registry; never touches `modified` / `created` markers
+--     from concurrent Edit/Write/ApplyPatch proposals.
+--   * ApplyPatch: closes one preview per file referenced in the patch text.
+--   * Other tools: closes the single preview keyed by file_path.
+--   * Always returns "" (no backend reads post-tool stdout).
+--   * Robust against malformed inputs (no raise).
+
+local post_tool = require("code-preview.post_tool")
+local changes   = require("code-preview.changes")
+
+local function payload(tool_name, tool_input, cwd)
+  return { tool_name = tool_name, cwd = cwd or "/proj", tool_input = tool_input }
+end
+
+describe("post_tool.handle (Bash status clear)", function()
+  before_each(function() changes.clear_all() end)
+
+  it("clears deleted markers", function()
+    changes.set("/proj/gone.txt", "deleted")
+    post_tool.handle(payload("Bash", { command = "rm gone.txt" }), "claudecode")
+    assert.is_nil(changes.get("/proj/gone.txt"))
+  end)
+
+  it("clears bash_modified / bash_created markers", function()
+    changes.set("/proj/a.txt", "bash_modified")
+    changes.set("/proj/b.txt", "bash_created")
+    post_tool.handle(payload("Bash", { command = "echo x > a.txt" }), "claudecode")
+    assert.is_nil(changes.get("/proj/a.txt"))
+    assert.is_nil(changes.get("/proj/b.txt"))
+  end)
+
+  it("preserves modified / created markers from concurrent edits", function()
+    -- An Edit proposal whose post-hook hasn't fired yet must survive a
+    -- concurrent Bash post-hook clearing its own origin-prefixed markers.
+    changes.set("/proj/edit.lua", "modified")
+    changes.set("/proj/new.lua",  "created")
+    changes.set("/proj/gone.txt", "deleted")
+    post_tool.handle(payload("Bash", { command = "rm gone.txt" }), "claudecode")
+    assert.equals("modified", changes.get("/proj/edit.lua"))
+    assert.equals("created",  changes.get("/proj/new.lua"))
+    assert.is_nil(changes.get("/proj/gone.txt"))
+  end)
+end)
+
+describe("post_tool.handle (return value)", function()
+  it("always returns empty string", function()
+    assert.equals("", post_tool.handle(payload("Bash",       { command = "ls" }), "claudecode"))
+    assert.equals("", post_tool.handle(payload("Edit",       { file_path = "/proj/x" }), "claudecode"))
+    assert.equals("", post_tool.handle(payload("ApplyPatch", { patch_text = "" }), "claudecode"))
+    assert.equals("", post_tool.handle(payload("Unknown",    {}), "claudecode"))
+  end)
+end)
+
+describe("post_tool.handle (robustness)", function()
+  it("missing tool_input does not raise", function()
+    assert.has_no.errors(function()
+      post_tool.handle({ tool_name = "Edit", cwd = "/proj" }, "claudecode")
+    end)
+  end)
+
+  it("empty patch_text is a no-op", function()
+    assert.has_no.errors(function()
+      post_tool.handle(payload("ApplyPatch", { patch_text = "" }), "claudecode")
+    end)
+  end)
+
+  it("unknown tool_name does not raise", function()
+    assert.has_no.errors(function()
+      post_tool.handle(payload("Read", { file_path = "/proj/x" }), "claudecode")
+    end)
+  end)
+end)