woods 2.0.0.beta2 → 2.0.0.beta3

data/lib/woods.rb

@@ -135,7 +135,7 @@ module Woods
                   :concurrent_extraction, :precompute_flows, :extract_navigation_edges, :enable_snapshots,
                   :session_tracer_enabled, :session_tracer_allow_production,
                   :session_store, :session_id_proc, :session_exclude_paths,
-                  :console_mcp_enabled, :console_mcp_path, :console_mcp_token,
+                  :console_mcp_enabled, :console_mcp_http_enabled, :console_mcp_path, :console_mcp_token,
                   :console_mcp_allowed_origins,
                   :console_redacted_columns,
                   :console_redacted_key_values, :console_embedded_read_tools,
@@ -147,13 +147,15 @@ module Woods
                   :unblocked_api_token, :unblocked_collection_id, :unblocked_repo_url,
                   :cache_store, :cache_options,
                   :dump_retention_count, :component_paths
-    attr_reader :embedding_model, :max_context_tokens, :similarity_threshold, :extractors, :pretty_json,
-                :context_format, :cache_enabled, :volatile_dependency_ratio,
+    attr_reader :retrieval_mode, :embedding_model, :max_context_tokens, :similarity_threshold, :extractors,
+                :pretty_json,
+                :context_format, :cache_enabled, :volatile_dependency_ratio, :volatile_dependency_limit_per_target,
                 :graph_cycle_limit, :graph_cycle_max_length,
                 :incremental_blast_radius_depth, :durable_payload_writes
 
     def initialize # rubocop:disable Metrics/MethodLength
       @output_dir = nil # Resolved lazily; Rails.root is nil at require time
+      @retrieval_mode = :semantic
       @embedding_model = 'text-embedding-3-small'
       @embedding_model_explicit = false
       @max_context_tokens = 8000
@@ -173,10 +175,13 @@ module Woods
       @session_id_proc = nil
       @session_exclude_paths = []
       @console_mcp_enabled = false
+      # Preserve existing HTTP setups. Stdio-only hosts explicitly disable
+      # HTTP while leaving the Console master switch enabled.
+      @console_mcp_http_enabled = true
       @console_mcp_path = '/mcp/console'
       # Accept token from config or env var. Nil by default — the railtie
-      # refuses to wire the middleware in production without a real token
-      # and only warns loudly in non-prod when unset.
+      # rejects production boot when HTTP Console is enabled without a real
+      # token, and warns in non-production. Stdio does not use this token.
       @console_mcp_token = ENV.fetch('WOODS_CONSOLE_MCP_TOKEN', nil)
       # Origins allowed to reach the embedded console MCP. Loopback only
       # by default; override in host initializers for tunneled or internal
@@ -209,6 +214,7 @@ module Woods
       @cache_options = {}     # { redis: client, cache: store, ttl: { embeddings: 86400, ... } }
       @dump_retention_count = 3
       @volatile_dependency_ratio = 3.0
+      @volatile_dependency_limit_per_target = nil
       @graph_cycle_limit = GraphAnalyzer::DEFAULT_CYCLE_LIMIT
       @graph_cycle_max_length = GraphAnalyzer::DEFAULT_CYCLE_MAX_LENGTH
       # nil = the unbounded transitive closure. See the setter for why the
@@ -255,6 +261,7 @@ module Woods
       @max_context_tokens = value
     end
 
+    # Deprecated compatibility setting; retrieval never applies this cutoff.
     # @param value [Numeric] Must be between 0.0 and 1.0 inclusive
     # @raise [ConfigurationError] if value is out of range or not numeric
     def similarity_threshold=(value)
@@ -265,6 +272,8 @@ module Woods
         raise ConfigurationError, "similarity_threshold must be between 0.0 and 1.0, got #{value.inspect}"
       end
 
+      warn '[woods] similarity_threshold is deprecated and does not filter retrieval results; ' \
+           'use explicit types/scopes and inspect returned ranking evidence instead.'
       @similarity_threshold = float_val
     end
 
@@ -317,6 +326,16 @@ module Woods
       @pretty_json = value
     end
 
+    # @param value [Symbol, String] semantic (default) or lexical
+    # @raise [ConfigurationError] if value is not a supported retrieval mode
+    def retrieval_mode=(value)
+      unless %w[semantic lexical].include?(value.to_s)
+        raise ConfigurationError, "retrieval_mode must be semantic or lexical, got #{value.inspect}"
+      end
+
+      @retrieval_mode = value.to_sym
+    end
+
     # @param value [Symbol] Must be one of :claude, :markdown, :plain, :json
     # @raise [ConfigurationError] if value is not a valid format
     def context_format=(value)
@@ -348,6 +367,16 @@ module Woods
       @volatile_dependency_ratio = value.to_f
     end
 
+    # Maximum volatile report edges per typed dependency, before the global
+    # report limit. `nil` preserves the unlimited default.
+    #
+    # @param value [Integer, nil] must be a positive Integer, or nil
+    # @raise [ConfigurationError] otherwise
+    def volatile_dependency_limit_per_target=(value)
+      @volatile_dependency_limit_per_target = validate_optional_positive_integer!(:volatile_dependency_limit_per_target,
+                                                                                  value)
+    end
+
     # How many distinct cycles {Woods::GraphAnalyzer#cycles} enumerates before
     # it stops. `nil` removes the cap and restores exhaustive enumeration.
     #
@@ -493,11 +522,8 @@ module Woods
     # @param output_dir [String] Override output directory
     # @return [Hash] Extraction results
     def extract!(output_dir: nil)
-      require_relative 'woods/extractor'
-
       dir = output_dir || configuration.output_dir
-      extractor = Extractor.new(output_dir: dir)
-      extractor.extract_all
+      with_extraction_writer(dir, &:extract_all)
     end
 
     # Perform incremental extraction
@@ -505,10 +531,23 @@ module Woods
     # @param changed_files [Array<String>] List of changed files
     # @return [Array<String>] Re-extracted unit identifiers
     def extract_changed!(changed_files)
+      with_extraction_writer(configuration.output_dir) { |extractor| extractor.extract_changed(changed_files) }
+    end
+
+    private
+
+    # One-shot public callers share the task/watch writer lock. Unlike a rake
+    # task, a library caller needs a typed timeout exception, not process exit.
+    def with_extraction_writer(output_dir)
       require_relative 'woods/extractor'
+      require_relative 'woods/rake_helpers'
 
-      extractor = Extractor.new(output_dir: configuration.output_dir)
-      extractor.extract_changed(changed_files)
+      RakeHelpers.woods_with_extraction_lock(output_dir, raise_on_timeout: true) do
+        extractor = Extractor.new(output_dir: output_dir)
+        result = yield extractor
+        extractor.raise_on_publication_failure!
+        result
+      end
     end
   end
 

data/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "woods-plugin",
   "description": "Woods user guides for Claude Code: set up, upgrade, configure MCP servers for, investigate codebases with, enable a repository's agents on, and diagnose the Woods Rails code-intelligence gem.",
-  "version": "2.3.0",
+  "version": "2.3.36",
   "author": {
     "name": "lost-in-the"
   },

data/plugin/hooks/adapters/normalize.jq

@@ -0,0 +1,15 @@
+def valid_string:
+  type == "string" and length > 0 and utf8bytelength <= 4096 and (contains("\u0000") | not);
+def invalid: error("Unsupported or malformed edit event; no refresh queued.");
+. as $input |
+if type != "object" then invalid
+elif $client == "claude" then
+  if .hook_event_name == "PostToolUse" and (["Write", "Edit", "MultiEdit"] | index($input.tool_name)) then
+    {version:1,root:.cwd,events:[{path:.tool_input.file_path,operation:"update"}]}
+  else invalid end
+elif $client == "opencode" and .version == 1 and .client == "opencode" then
+  {version:1,root:.root,events:.events}
+else invalid end
+| if (.root | valid_string) and (.root | startswith("/")) and (.events | type == "array" and length > 0 and length <= 1000)
+  and all(.events[]; type == "object" and (.path | valid_string) and (.operation as $operation | ["add","update","delete"] | index($operation)))
+  then .events |= (map({path,operation}) | unique_by(.path,.operation)) else invalid end

data/plugin/hooks/adapters/normalize.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'json'
+
+# Standalone stdlib fallback for hosts without jq; never loads the Woods bundle.
+module WoodsHookEvent
+  module_function
+
+  def string?(value)
+    value.is_a?(String) && !value.empty? && value.bytesize <= 4096 && !value.include?("\0") && value.valid_encoding?
+  end
+
+  def normalize(client, input)
+    raise ArgumentError unless input.is_a?(Hash)
+
+    root, events = client_event(client, input)
+    validate_envelope(root, events)
+
+    normalized = events.map { |event| normalize_event(event) }.uniq
+    { 'version' => 1, 'root' => root,
+      'events' => normalized.sort_by { |event| event.values_at('path', 'operation') } }
+  end
+
+  def validate_envelope(root, events)
+    raise ArgumentError unless string?(root) && root.start_with?('/')
+    raise ArgumentError unless events.is_a?(Array) && events.size.between?(1, 1000)
+  end
+
+  def client_event(client, input)
+    case client
+    when 'claude' then claude_event(input)
+    when 'opencode'
+      raise ArgumentError unless input['version'] == 1 && input['client'] == 'opencode'
+
+      [input['root'], input['events']]
+    else raise ArgumentError
+    end
+  end
+
+  def claude_event(input)
+    raise ArgumentError unless input['hook_event_name'] == 'PostToolUse' &&
+                               %w[Write Edit MultiEdit].include?(input['tool_name']) &&
+                               input['tool_input'].is_a?(Hash)
+
+    [input['cwd'], [{ 'path' => input.fetch('tool_input').fetch('file_path'), 'operation' => 'update' }]]
+  end
+
+  def normalize_event(event)
+    raise ArgumentError unless event.is_a?(Hash) && string?(event['path']) &&
+                               %w[add update delete].include?(event['operation'])
+
+    { 'path' => event['path'], 'operation' => event['operation'] }
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    puts JSON.generate(WoodsHookEvent.normalize(ARGV.fetch(0), JSON.parse($stdin.read(1_048_577))))
+  rescue JSON::ParserError, ArgumentError, KeyError, TypeError
+    warn '[Woods hooks] Unsupported or malformed edit event; no refresh queued.'
+    exit 1
+  end
+end

data/plugin/hooks/hooks.json

@@ -11,6 +11,16 @@
             "timeout": 600
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/woods-context.sh\" PostToolUse",
+            "timeout": 2
+          }
+        ]
       }
     ],
     "SessionStart": [
@@ -23,6 +33,16 @@
             "timeout": 20
           }
         ]
+      },
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/woods-context.sh\" SessionStart",
+            "timeout": 2
+          }
+        ]
       }
     ]
   }

data/plugin/hooks/woods-context.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Independently opt-in synchronous hints. The process deadline includes stdin,
+# bundle startup, index/cache preparation, source verification and state I/O.
+set -u
+[ "${WOODS_HOOKS_DISABLED:-0}" = 1 ] && exit 0
+[ "${WOODS_HOOK_CONTEXT_ENABLED:-0}" = 1 ] || exit 0
+case "${1:-}" in SessionStart|PostToolUse) ;; *) exit 0 ;; esac
+exec 3<&0
+capture_response() {
+  runner=""; timer=""
+  cleanup() {
+    [ -z "$runner" ] || kill -KILL -- "-$runner" 2>/dev/null || true
+    [ -z "$timer" ] || kill -KILL -- "-$timer" 2>/dev/null || true
+  }
+  trap cleanup EXIT
+  trap 'exit 1' INT TERM
+  set -m
+  command="${WOODS_HOOK_CONTEXT_COMMAND:-bundle exec woods-hook-context}"
+  ( $command "$1" ) <&3 2>/dev/null &
+  runner=$!
+  ( sleep 0.85; kill -KILL -- "-$runner" 2>/dev/null ) >/dev/null 2>&1 &
+  timer=$!
+  wait "$runner" 2>/dev/null
+  status=$?
+  cleanup
+  wait "$timer" 2>/dev/null || true
+  runner=""; timer=""
+  # Carry the producer status in-band: Bash 3.2 cannot wait on this
+  # process-substitution PID. Cleanup finishes before the final status frame.
+  printf '\n%s' "$status"
+}
+# Bash 3.2-compatible process substitution: buffer the bounded response until
+# EOF and successful producer exit. Never forward a timed-out partial envelope.
+exec 4< <(capture_response "$1")
+supervisor=$!
+trap 'kill -TERM "$supervisor" 2>/dev/null; exit 0' INT TERM
+response=""
+# <=2048 payload bytes + newline/status byte; one extra byte rejects overflow.
+LC_ALL=C IFS= read -r -d '' -n 2051 response <&4
+read_status=$?
+exec 4<&-
+if [ "$read_status" -ne 1 ]; then
+  kill -TERM "$supervisor" 2>/dev/null || true
+  exit 0
+fi
+case "$response" in *$'\n'0) response="${response%$'\n'0}" ;; *) exit 0 ;; esac
+wait "$supervisor" 2>/dev/null || true
+# One builtin write of an already complete <=2KiB envelope to the client pipe.
+printf '%s' "$response"
+exit 0

data/plugin/hooks/woods-input-rules.sh

@@ -0,0 +1,159 @@
+# Generated by script/generate-hook-rules; do not edit.
+woods_input_action() {
+  local path="$1" operation="${2:-update}"
+  if [[ "$path" == Gemfile ]]; then printf full; return; fi
+  if [[ "$path" == Gemfile.lock ]]; then printf full; return; fi
+  if [[ "$path" == .ruby-version ]]; then printf full; return; fi
+  if [[ "$path" == config/application.rb ]]; then printf full; return; fi
+  if [[ "$path" == config/boot.rb ]]; then printf full; return; fi
+  if [[ "$path" == config/environment.rb ]]; then printf full; return; fi
+  if [[ "$path" == config/database.yml ]]; then printf full; return; fi
+  if [[ "$path" == config/credentials.yml.enc ]]; then printf full; return; fi
+  if [[ "$path" == config/master.key ]]; then printf full; return; fi
+  if [[ "$path" == db/schema.rb ]]; then printf full; return; fi
+  if [[ "$path" == db/structure.sql ]]; then printf full; return; fi
+  if [[ "$path" == config/initializers/* ]]; then printf full; return; fi
+  if [[ "$path" == config/environments/* ]]; then printf full; return; fi
+  if [[ "$path" == config/credentials/* ]]; then printf full; return; fi
+  if [[ "$path" =~ ^config/settings\.ya?ml$ ]]; then printf full; return; fi
+  if [[ "$path" =~ ^config/settings/[^/]+\.ya?ml$ ]]; then printf full; return; fi
+  if [[ "$path" =~ ^config/(cable|storage|sidekiq|puma|cache|queue)\.ya?ml$ ]]; then printf full; return; fi
+  if [[ "$path" =~ ^\.env(\..+)?$ ]]; then printf full; return; fi
+  if { { { [[ "$path" == *.rb ]]; } && { [[ "$path" == app/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.rb ]]; } && { [[ "$path" == app/services/* ]] || [[ "$path" == app/interactors/* ]] || [[ "$path" == app/operations/* ]] || [[ "$path" == app/commands/* ]] || [[ "$path" == app/use_cases/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.rb ]]; } && { [[ "$path" == app/jobs/* ]] || [[ "$path" == app/workers/* ]] || [[ "$path" == app/sidekiq/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.rb ]]; } && { [[ "$path" == app/serializers/* ]] || [[ "$path" == app/blueprinters/* ]] || [[ "$path" == app/decorators/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.rb ]]; } && { [[ "$path" == app/managers/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.rb ]]; } && { [[ "$path" == app/policies/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.rb ]]; } && { [[ "$path" == app/validators/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.rb ]]; } && { [[ "$path" == app/policies/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.rb ]]; } && { [[ "$path" == app/decorators/* ]] || [[ "$path" == app/presenters/* ]] || [[ "$path" == app/form_objects/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.rb ]]; } && { [[ "$path" == config/initializers/* ]] || [[ "$path" == config/environments/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.rb ]]; } && [[ "$path" == */concerns/* ]] && { [[ "$path" == app/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { [[ "$path" != */concerns/* ]] && { [[ "$path" == *.rb ]]; } && { [[ "$path" == app/* ]] || [[ "$path" == lib/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.rb ]]; } && { [[ "$path" == app/graphql/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.yml ]]; } && { [[ "$path" == config/locales/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.rake ]]; } && { [[ "$path" == lib/tasks/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.html.erb ]] || [[ "$path" == *.erb ]]; } && { [[ "$path" == app/views/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.rb ]]; } && { [[ "${path%/*}" == db/migrate ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { [[ "$path" != */concerns/* ]] && { [[ "$path" == *.rb ]]; } && { [[ "$path" == app/models/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { [[ "$path" != */tasks/* ]] && [[ "$path" != */generators/* ]] && { [[ "$path" == *.rb ]]; } && { [[ "$path" == lib/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *_spec.rb ]]; } && { [[ "$path" == spec/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *_test.rb ]]; } && { [[ "$path" == test/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.rb ]]; } && { [[ "$path" == app/controllers/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.rb ]]; } && { [[ "$path" == app/models/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.erb ]]; } && { [[ "$path" == app/views/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { [[ "$path" == config/routes.rb ]] || { { [[ "$path" == config/routes/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { [[ "$path" == config/routes.rb ]] || [[ "$path" == Gemfile.lock ]] || { { [[ "$path" == config/routes/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { [[ "$path" == config/application.rb ]] || [[ "$path" == Gemfile.lock ]] || { { [[ "$path" == config/initializers/* ]] || [[ "$path" == config/environments/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { [[ "$path" == config/recurring.yml ]] || [[ "$path" == config/sidekiq_cron.yml ]] || [[ "$path" == config/schedule.rb ]] || { false; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.rb ]]; } && { [[ "$path" == app/models/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.rb ]]; } && { [[ "$path" == spec/factories/* ]] || [[ "$path" == test/factories/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.sql ]]; } && { [[ "$path" == db/views/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { { [[ "$path" == *.rb ]]; } && { [[ "$path" == app/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { [[ "$path" == Gemfile.lock ]] || { false; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  if { { [[ "$path" != *node_modules/* ]] && [[ "$path" != *vendor/* ]] && [[ "$path" != *tmp/* ]] && [[ "$path" != *bin/* ]] && [[ "$path" != *script/* ]] && { [[ "${path##*/}" == package.yml ]] || [[ "${path##*/}" == packwerk.yml ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
+  printf ignore
+}

data/plugin/hooks/woods-opencode.mjs

@@ -0,0 +1,65 @@
+// OpenCode 1.18.27 tool.execute.after adapter. Keep callback metadata private:
+// only the worktree and affected paths cross into the shared refresh runner.
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const runner = fileURLToPath(new URL("./woods-refresh.sh", import.meta.url));
+const enabled = () => process.env.WOODS_HOOKS_ENABLED === "1" && process.env.WOODS_HOOKS_DISABLED !== "1";
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const pathString = (value) => typeof value === "string" && value.length > 0 && !value.includes("\0");
+
+function eventsFor(input, output) {
+  if (!object(input) || !object(output) || !object(output.metadata)) throw new Error("invalid event");
+  const metadata = output.metadata;
+  if (input.tool === "apply_patch") {
+    if (!Array.isArray(metadata.files) || !metadata.files.length || metadata.files.length > 1000) throw new Error("missing file metadata");
+    return metadata.files.flatMap((file) => {
+      if (!object(file) || !pathString(file.filePath)) throw new Error("invalid file metadata");
+      if (file.type === "move") {
+        if (!pathString(file.movePath)) throw new Error("missing move target");
+        return [{ path: file.filePath, operation: "delete" }, { path: file.movePath, operation: "add" }];
+      }
+      if (!["add", "update", "delete"].includes(file.type)) throw new Error("unknown file operation");
+      return [{ path: file.filePath, operation: file.type }];
+    });
+  }
+  if (input.tool === "write") {
+    if (!pathString(metadata.filepath) || typeof metadata.exists !== "boolean") throw new Error("invalid write metadata");
+    return [{ path: metadata.filepath, operation: metadata.exists ? "update" : "add" }];
+  }
+  if (input.tool === "edit") {
+    if (!object(metadata.filediff) || !pathString(metadata.filediff.file)) throw new Error("invalid edit metadata");
+    return [{ path: metadata.filediff.file, operation: "update" }];
+  }
+  throw new Error("unsupported tool");
+}
+
+export default async function WoodsHooks({ directory, worktree }) {
+  return {
+    "tool.execute.after": async (input, output) => {
+      if (!enabled() || !["apply_patch", "write", "edit"].includes(input?.tool)) return;
+      try {
+        if (!pathString(directory) || !pathString(worktree) || !path.isAbsolute(directory) || !path.isAbsolute(worktree)) {
+          throw new Error("invalid project context");
+        }
+        const relative = path.relative(worktree, directory);
+        if (relative === ".." || relative.startsWith("../") || path.isAbsolute(relative)) throw new Error("foreign project");
+        const payload = JSON.stringify({ version: 1, client: "opencode", root: directory, events: eventsFor(input, output) });
+        if (Buffer.byteLength(payload) > 49_152) throw new Error("event too large");
+        // The shared runner durably queues and owns its own deadline. Tool
+        // completion only hands off the event; it does not claim refresh success.
+        await new Promise((resolve, reject) => {
+          const child = spawn("bash", [runner, "opencode"], {
+            cwd: directory, detached: true, stdio: ["pipe", "ignore", "inherit"],
+          });
+          child.once("error", reject);
+          child.stdin.once("error", reject);
+          child.stdin.end(payload, () => { child.unref(); resolve(); });
+        });
+      } catch {
+        console.error("[Woods hooks] Unsupported, malformed or undeliverable OpenCode edit event; refresh not confirmed.");
+      }
+    },
+  };
+}