rubyn-code 0.5.0 → 0.7.0

data/lib/rubyn_code/hooks/external_dispatcher.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require_relative 'event_map'
+require_relative 'response'
+require_relative 'settings_json_loader'
+require_relative 'subprocess_executor'
+
+module RubynCode
+  module Hooks
+    # Dispatches hook events to external commands configured in settings.json.
+    #
+    # The dispatcher sits alongside the in-process Hooks::Runner. It does NOT
+    # replace it — existing pre/post_tool_use YAML hooks and Ruby callables
+    # keep working. New code that wants Claude Code-style control flow (block,
+    # stopReason, additionalContext) fires through this dispatcher instead.
+    #
+    # Wire it into the agent loop wherever a return value matters:
+    #
+    #   response = dispatcher.fire(:pre_tool_use, tool_name:, tool_input:)
+    #   raise ToolBlockedError, response.reason if response.block?
+    #
+    # For events where return values don't matter (e.g. SessionStart logging),
+    # call #fire and ignore the response — but still inspect #stop? when the
+    # caller wants to honour a stop signal mid-stream.
+    class ExternalDispatcher
+      DEFAULT_TIMEOUT = 60
+
+      attr_reader :project_root, :config
+
+      # @param project_root [String]
+      # @param config [Hash<String, Array<Hash>>] result of SettingsJsonLoader#load
+      # @param executor [SubprocessExecutor, nil] injectable for tests
+      # @param logger [#warn, nil] injectable for tests
+      def initialize(project_root:, config: nil, executor: nil, logger: nil)
+        @project_root = project_root
+        @config = config || SettingsJsonLoader.new(project_root: project_root).load
+        @executor = executor || SubprocessExecutor.new(project_root: project_root)
+        @logger = logger || method(:default_log)
+      end
+
+      # @return [Boolean] true if any external hook is configured for this event
+      def configured_for?(internal_event)
+        external = EventMap.external(internal_event)
+        return false unless external
+
+        Array(@config[external]).any?
+      end
+
+      # Fires all configured external hooks for the given internal event.
+      #
+      # Each matcher group's commands are run sequentially (the order they
+      # appear in settings.json). Within a group, commands run in declared
+      # order. Hook errors and timeouts are logged but do not abort the
+      # remaining hooks — matching Claude Code's "best effort" semantics.
+      #
+      # @param internal_event [Symbol] one of TO_EXTERNAL keys
+      # @param payload [Hash] event-specific payload (tool_name, tool_input, etc.)
+      # @return [Response] the merged response from all hooks (first block/stop
+      #   wins; additionalContext is concatenated)
+      def fire(internal_event, **payload)
+        external = EventMap.external(internal_event)
+        return empty_response unless external
+
+        groups = Array(@config[external])
+        return empty_response if groups.empty?
+
+        envelope = build_envelope(external, payload)
+        collected = collect_responses(groups, envelope, payload)
+        Response.new(raw: build_merged(collected, external))
+      end
+
+      private
+
+      def empty_response
+        Response.new(raw: {})
+      end
+
+      # Runs each configured hook command and collects its decision fields.
+      # First block/stop wins; additionalContext/suppressOutput are also
+      # first-wins for simplicity (matches Claude Code's documented behaviour).
+      def collect_responses(groups, envelope, payload)
+        accumulator = {
+          block_reason: nil, stop_reason: nil,
+          additional_context: nil, suppress_output: false
+        }
+
+        groups.each do |group|
+          next unless matches?(group['matcher'], payload)
+
+          group['hooks'].each do |command_cfg|
+            response = invoke_command(command_cfg, envelope)
+            merge_response!(accumulator, response)
+          end
+        end
+
+        accumulator
+      end
+
+      def merge_response!(accumulator, response)
+        return unless response
+
+        accumulator[:block_reason]       ||= response.reason if response.block?
+        accumulator[:stop_reason]        ||= response.stop_reason if response.stop?
+        accumulator[:additional_context] ||= response.additional_context if response.additional_context?
+        accumulator[:suppress_output]    ||= response.suppress_output?
+      end
+
+      def invoke_command(command_cfg, envelope)
+        command = command_cfg['command']
+        return nil if command.nil? || command.empty?
+
+        timeout = command_cfg['timeout'] || DEFAULT_TIMEOUT
+        env     = command_cfg['env'] || {}
+
+        raw = @executor.run(
+          command: command,
+          env: env,
+          payload: envelope,
+          timeout: timeout
+        )
+        Response.new(raw: raw || {})
+      rescue SubprocessExecutor::TimeoutError, SubprocessExecutor::ExecutionError => e
+        @logger.call("[ExternalDispatcher] hook '#{command}' failed: #{e.message}")
+        nil
+      end
+
+      def build_envelope(external_event, payload)
+        base_envelope(external_event, payload).merge(event_specific_fields(external_event, payload)).compact
+      end
+
+      def base_envelope(external_event, payload)
+        {
+          'hookEventName' => external_event,
+          'sessionId' => payload[:session_id] || payload['session_id'] || ENV.fetch('RUBYN_SESSION_ID', nil),
+          'cwd' => @project_root,
+          'transcriptPath' => payload[:transcript_path] || ENV.fetch('RUBYN_TRANSCRIPT_PATH', nil)
+        }.compact
+      end
+
+      def event_specific_fields(external_event, payload)
+        case external_event
+        when 'PreToolUse', 'PostToolUse' then tool_envelope_fields(payload)
+        when 'UserPromptSubmit'          then { 'prompt' => payload[:prompt] || payload['text'] }
+        when 'Notification'              then { 'message' => payload[:message] }
+        when 'SessionStart', 'SessionEnd', 'Stop', 'SubagentStop' then session_envelope_fields(payload)
+        when 'PreCompact' then { 'trigger' => payload[:trigger] || 'auto' }
+        else {}
+        end
+      end
+
+      def tool_envelope_fields(payload)
+        {
+          'toolName' => payload[:tool_name] || payload['tool_name'],
+          'toolInput' => payload[:tool_input] || payload['tool_input'] || {}
+        }
+      end
+
+      def session_envelope_fields(payload)
+        return {} unless payload[:reason]
+
+        { 'reason' => payload[:reason] }
+      end
+
+      def matches?(matcher, payload)
+        return true if matcher.nil? || matcher == '*'
+
+        target = payload[:tool_name] || payload['tool_name'] || payload[:session_id] || payload['session_id']
+        return true if target.nil? # No subject to match — accept all
+
+        begin
+          Regexp.new(matcher).match?(target.to_s)
+        rescue RegexpError
+          # Fall back to literal equality if matcher isn't a valid regex.
+          matcher.to_s == target.to_s
+        end
+      end
+
+      def build_merged(collected, hook_event_name)
+        merged = {}
+        merged['decision']     = 'block' if collected[:block_reason]
+        merged['reason']       = collected[:block_reason] if collected[:block_reason]
+        merged['stopReason']   = collected[:stop_reason] if collected[:stop_reason]
+        merged['continue']     = false if collected[:stop_reason]
+        merged['suppressOutput'] = true if collected[:suppress_output]
+        return merged unless collected[:additional_context]
+
+        merged['hookSpecificOutput'] = {
+          'hookEventName' => hook_event_name,
+          'additionalContext' => collected[:additional_context]
+        }
+        merged
+      end
+
+      def default_log(message)
+        warn message
+      end
+    end
+  end
+end

data/lib/rubyn_code/hooks/goal_hook.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Hooks
+    # A Stop hook that keeps the agent working until a session goal is met.
+    #
+    # When active, firing the :stop event asks an evaluator whether the goal
+    # condition is satisfied. If it is, the hook deactivates itself (the goal
+    # "auto-clears") and allows the agent to stop. If not, it returns a block
+    # decision whose reason is re-injected into the conversation, nudging the
+    # agent to keep working.
+    #
+    # A max-attempts safety valve prevents an unsatisfiable goal from looping
+    # forever — after MAX_ATTEMPTS consecutive blocks the hook gives up and
+    # lets the agent stop.
+    class GoalHook
+      DEFAULT_MAX_ATTEMPTS = 12
+
+      # @return [String] the goal condition
+      attr_reader :condition
+
+      # @param condition [String] plain-language goal condition
+      # @param evaluator [#call, nil] judges completion; nil disables auto-clear
+      # @param max_attempts [Integer] consecutive blocks before giving up
+      def initialize(condition:, evaluator: nil, max_attempts: DEFAULT_MAX_ATTEMPTS)
+        @condition = condition
+        @evaluator = evaluator
+        @max_attempts = max_attempts
+        @attempts = 0
+        @active = true
+      end
+
+      # @return [Boolean]
+      def active? = @active
+
+      # Cancel the goal early (e.g. `/goal clear`).
+      # @return [void]
+      def clear!
+        @active = false
+      end
+
+      # Fired on the :stop event by Hooks::Runner.
+      #
+      # @param conversation [Agent::Conversation, nil] recent work, for judging
+      # @return [Hash, nil] { block: true, reason: } to keep working, else nil
+      def call(conversation: nil, **_kwargs)
+        return nil unless @active
+
+        if goal_met?(conversation)
+          @active = false
+          return nil
+        end
+
+        @attempts += 1
+        if @attempts >= @max_attempts
+          @active = false
+          RubynCode::Debug.warn("Goal abandoned after #{@max_attempts} attempts: #{@condition}")
+          return nil
+        end
+
+        { block: true, reason: reminder }
+      end
+
+      private
+
+      def goal_met?(conversation)
+        return false unless @evaluator
+
+        @evaluator.call(condition: @condition, conversation: conversation)
+      rescue StandardError => e
+        RubynCode::Debug.warn("Goal hook evaluation error: #{e.message}")
+        false
+      end
+
+      def reminder
+        <<~TEXT.strip
+          Your active goal is not yet complete:
+
+            #{@condition}
+
+          Keep working toward it now — do not stop or ask what to do next.
+          If you are certain the goal is genuinely and fully met, state that
+          explicitly and explain how it was satisfied.
+        TEXT
+      end
+    end
+  end
+end

data/lib/rubyn_code/hooks/response.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Hooks
+    # Normalized response from an external (Claude Code-style) hook.
+    #
+    # External hooks communicate control-flow decisions and prompt augmentations
+    # back to the agent via JSON. This class wraps the parsed response and
+    # provides predicate methods so call sites don't have to know the response
+    # shape details.
+    #
+    # Supported response shapes (any subset can be combined):
+    #
+    #   { "continue": false, "stopReason": "Denied by policy" }
+    #     — ask the agent to stop. stopReason is appended to the conversation.
+    #
+    #   { "decision": "block", "reason": "rm -rf is forbidden" }
+    #     — for PreToolUse only; abort this tool call before it runs.
+    #
+    #   { "decision": "approve" } or { "decision": undefined }
+    #     — allow the call to proceed (default).
+    #
+    #   {
+    #     "hookSpecificOutput": {
+    #       "hookEventName": "PreToolUse",
+    #       "additionalContext": "Project policy: always run rubocop before commit"
+    #     }
+    #   }
+    #     — additionalContext is injected into the next system prompt / LLM
+    #       request so the model sees the hook's guidance.
+    #
+    #   { "suppressOutput": true }
+    #     — UI hook wants to silence default output rendering (e.g. streamed
+    #       json progress). Best-effort; honoured by the renderer when present.
+    class Response
+      # @return [String, nil] reason text for block/stop decisions
+      attr_reader :reason
+
+      # @return [String, nil] additionalContext injected into the next LLM call
+      attr_reader :additional_context
+
+      attr_reader :hook_event_name, :stop_reason
+
+      def initialize(raw: {})
+        @raw = raw || {}
+        @decision      = @raw['decision']
+        @continue      = @raw.key?('continue') ? @raw['continue'] : true
+        @stop_reason   = @raw['stopReason']
+        @reason        = @raw['reason']
+        @suppress      = @raw['suppressOutput'] == true
+
+        specific = @raw['hookSpecificOutput'].is_a?(Hash) ? @raw['hookSpecificOutput'] : {}
+        @hook_event_name = specific['hookEventName']
+        @additional_context = specific['additionalContext']
+      end
+
+      # @return [Boolean] true if the hook says to abort a PreToolUse call
+      def block?
+        @decision == 'block'
+      end
+
+      # @return [Boolean] true if the hook says to stop the agent entirely
+      def stop?
+        @continue == false
+      end
+
+      # @return [Boolean] true if the hook has context to inject
+      def additional_context?
+        !@additional_context.nil? && !@additional_context.to_s.empty?
+      end
+
+      # @return [Boolean] true if the hook wants output suppressed
+      def suppress_output?
+        @suppress
+      end
+
+      # @return [Hash] the raw JSON response (for debugging/logging)
+      def to_h
+        @raw
+      end
+    end
+  end
+end

data/lib/rubyn_code/hooks/runner.rb

@@ -8,10 +8,18 @@ module RubynCode
     # caught and logged rather than allowed to crash the agent. Special
     # semantics apply to :pre_tool_use (deny gating) and :post_tool_use
     # (output transformation).
+    #
+    # The runner can also fan out to an external hook dispatcher (see
+    # ExternalDispatcher) which spawns Claude Code-style hook commands
+    # configured in settings.json. External hooks participate in the same
+    # deny/block decisions as in-process hooks.
     class Runner
       # @param registry [Hooks::Registry] the hook registry to draw from
-      def initialize(registry: Registry.new)
+      # @param external_dispatcher [Hooks::ExternalDispatcher, nil] optional
+      #   dispatcher for Claude Code-style external hook commands
+      def initialize(registry: Registry.new, external_dispatcher: nil)
         @registry = registry
+        @external_dispatcher = external_dispatcher
       end
 
       # Fires all hooks for the given event with the supplied context.
@@ -24,20 +32,70 @@ module RubynCode
       #   - all others => nil
       def fire(event, **context)
         hooks = @registry.hooks_for(event)
-        return if hooks.empty?
+        external_response = fire_external(event, **context)
 
         case event
         when :pre_tool_use
-          fire_pre_tool_use(hooks, context)
+          merge_pre_tool_use(fire_pre_tool_use(hooks, context), external_response)
         when :post_tool_use
+          # External hooks contribute additionalContext (read by the LLM
+          # caller) but do not transform tool output — that's a job for
+          # in-process hooks only.
           fire_post_tool_use(hooks, context)
+        when :stop
+          merge_stop(fire_stop(hooks, context), external_response)
         else
           fire_generic(hooks, event, context)
+          external_response&.additional_context
         end
       end
 
       private
 
+      # @return [Hooks::Response, nil] nil when no external dispatcher or
+      #   no hooks are configured for this event.
+      def fire_external(event, **context)
+        return nil unless @external_dispatcher
+
+        @external_dispatcher.fire(event, **context)
+      rescue StandardError => e
+        warn "[RubynCode::Hooks] External dispatcher error during #{event}: #{e.class}: #{e.message}"
+        nil
+      end
+
+      # In-process deny takes precedence over external block. Either way,
+      # if any source denies, return a deny hash.
+      def merge_pre_tool_use(in_process_result, external_response)
+        return in_process_result if in_process_result.is_a?(Hash) && in_process_result[:deny]
+
+        return nil unless external_response&.block?
+
+        { deny: true, reason: external_response.reason || 'Blocked by external hook' }
+      end
+
+      # Same precedence for stop: in-process block wins; external stop otherwise.
+      def merge_stop(in_process_result, external_response)
+        return in_process_result if in_process_result.is_a?(Hash) && in_process_result[:block]
+
+        return nil unless external_response&.stop?
+
+        { block: true, reason: external_response.stop_reason || 'Stopped by external hook' }
+      end
+
+      # For :stop, if any hook returns a hash with { block: true }, execution
+      # stops and the block result is returned — signalling the agent loop to
+      # keep working instead of finalizing (e.g. an active /goal).
+      def fire_stop(hooks, context)
+        hooks.each do |hook|
+          result = safe_call(hook, :stop, context)
+          next unless result.is_a?(Hash) && result[:block]
+
+          return { block: true, reason: result[:reason] || 'Stop blocked by hook' }
+        end
+
+        nil
+      end
+
       # For :pre_tool_use, if any hook returns a hash with { deny: true },
       # execution stops and the deny result is returned immediately.
       def fire_pre_tool_use(hooks, context)

data/lib/rubyn_code/hooks/settings_json_loader.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RubynCode
+  module Hooks
+    # Loads external hook commands from a Claude Code-compatible settings.json.
+    #
+    # Schema (matches Claude Code's hook config):
+    #
+    #   {
+    #     "hooks": {
+    #       "PreToolUse": [
+    #         {
+    #           "matcher": "bash|write_file",        // regex or "*"
+    #           "hooks": [
+    #             { "type": "command",
+    #               "command": "/usr/local/bin/policy-check",
+    #               "timeout": 60,
+    #               "env": { "FOO": "bar" }            // optional
+    #             }
+    #           ]
+    #         }
+    #       ],
+    #       "PostToolUse":      [ ... ],
+    #       "UserPromptSubmit": [ ... ],
+    #       "SessionStart":     [ ... ],
+    #       "SessionEnd":       [ ... ],
+    #       "Stop":             [ ... ],
+    #       "SubagentStop":     [ ... ],
+    #       "PreCompact":       [ ... ],
+    #       "Notification":     [ ... ]
+    #     }
+    #   }
+    #
+    # "matcher" may be:
+    #   - a regex string matched against the tool name (PreToolUse/PostToolUse)
+    #     or the session id (other events accept any value);
+    #   - "*" to match everything;
+    #   - omitted/null to match everything.
+    #
+    # The loader does not validate that commands exist on disk — that's the
+    # Executor's job (it will fail at fire time with a clear error).
+    class SettingsJsonLoader
+      class LoadError < RubynCode::Error
+      end
+
+      # @return [Array<String>] paths the loader will try, in order
+      attr_reader :search_paths
+
+      # @param project_root [String] used to locate .rubyn-code/settings.json
+      # @param home_dir [String, nil] override for ~/.rubyn-code; defaults to Defaults::HOME_DIR
+      def initialize(project_root:, home_dir: nil)
+        @home_dir = home_dir || Config::Defaults::HOME_DIR
+        @project_root = project_root
+        @search_paths = [
+          File.join(@project_root, '.rubyn-code', 'settings.json'),
+          File.join(@home_dir, 'settings.json')
+        ].freeze
+      end
+
+      # Loads and merges settings.json from project + global.
+      #
+      # Project wins for the same matcher/event combination: if both files
+      # define a hook for the same event, the project's hook runs first and
+      # the global hook runs after, mirroring Claude Code's behaviour.
+      #
+      # @return [Hash<String, Array<Hash>>] { event_name => [matcher_group, ...] }
+      #   where each matcher_group is { "matcher" => String, "hooks" => [command_hash, ...] }
+      def load
+        merged = {}
+        @search_paths.each do |path|
+          next unless File.exist?(path)
+
+          data = parse_file(path)
+          merge_into!(merged, data['hooks'] || {})
+        end
+        merged
+      end
+
+      private
+
+      def parse_file(path)
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError => e
+        raise LoadError, "Failed to parse hook settings at #{path}: #{e.message}"
+      end
+
+      def merge_into!(merged, hooks_section)
+        hooks_section.each do |event_name, matcher_groups|
+          next unless matcher_groups.is_a?(Array)
+
+          merged[event_name] ||= []
+          matcher_groups.each do |group|
+            next unless group.is_a?(Hash)
+
+            commands = Array(group['hooks']).select { |h| h.is_a?(Hash) && h['type'] == 'command' }
+            next if commands.empty?
+
+            merged[event_name] << {
+              'matcher' => group['matcher'] || '*',
+              'hooks' => commands
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/hooks/subprocess_executor.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require 'timeout'
+
+module RubynCode
+  module Hooks
+    # Spawns external hook commands and exchanges JSON with them.
+    #
+    # Protocol (matches Claude Code):
+    #   1. Spawn the command with { env, chdir: project_root }.
+    #   2. Write one JSON line to stdin:
+    #        { "hookEventName": "PreToolUse",
+    #          "sessionId": "...",
+    #          "toolName": "bash",          // when applicable
+    #          "toolInput": { ... },        // when applicable
+    #          "prompt": "user text..." }   // when applicable
+    #   3. Close stdin.
+    #   4. Read stdout until EOF or timeout. Parse as JSON.
+    #      - One JSON object spanning the whole output, OR
+    #      - Newline-delimited JSON (first parseable line wins).
+    #   5. Stderr is captured and logged but not parsed.
+    #
+    # The executor is stateless — each call spawns a fresh process. This is
+    # intentional: hooks must not keep state between invocations, and process
+    # startup cost (~30ms on macOS) is negligible compared to typical tool
+    # execution time.
+    class SubprocessExecutor
+      DEFAULT_TIMEOUT = 60 # seconds
+
+      class ExecutionError < RubynCode::Error
+      end
+
+      class TimeoutError < ExecutionError
+      end
+
+      # @param project_root [String] working directory for spawned processes
+      # @param default_timeout [Integer] fallback timeout when a hook entry
+      #   does not specify its own
+      def initialize(project_root:, default_timeout: DEFAULT_TIMEOUT)
+        @project_root = project_root
+        @default_timeout = default_timeout
+      end
+
+      # Runs a single hook command with the given event payload.
+      #
+      # @param command [String] executable path
+      # @param args [Array<String>] arguments (rarely used; settings.json
+      #   typically embeds everything in the command string)
+      # @param env [Hash<String, String>] additional environment variables
+      # @param payload [Hash] the JSON payload (must include :hookEventName)
+      # @param timeout [Integer, nil] per-call timeout override
+      # @return [Hash] the parsed JSON response from stdout (empty hash if no output)
+      # @raise [ExecutionError] on spawn failure
+      # @raise [TimeoutError] if the command does not finish in time
+      def run(command:, payload:, args: [], env: {}, timeout: nil)
+        timeout ||= @default_timeout
+        env = default_env.merge(env)
+
+        stdout, _stderr, = invoke(command, args, env, payload, timeout)
+        parse_response(stdout)
+      rescue Timeout::Error => e
+        raise TimeoutError, "Hook command '#{command}' timed out after #{timeout}s: #{e.message}"
+      end
+
+      private
+
+      def default_env
+        # Open3 replaces the entire env when env: is given, so inherit the
+        # parent's environment first and add our hook-specific markers.
+        ENV.to_h.merge(
+          'RUBYN_HOOK_EVENT' => '1',
+          'CLAUDE_PROJECT_DIR' => @project_root
+        )
+      end
+
+      def invoke(command, args, env, payload, timeout)
+        Timeout.timeout(timeout) do
+          Open3.capture3(env, command, *args, chdir: @project_root, stdin_data: JSON.generate(payload))
+        end
+      rescue Errno::ENOENT => e
+        raise ExecutionError, "Hook command not found: #{command} (#{e.message})"
+      rescue SystemCallError => e
+        raise ExecutionError, "Failed to spawn hook command '#{command}': #{e.message}"
+      end
+
+      def parse_response(stdout)
+        return {} if stdout.nil? || stdout.strip.empty?
+
+        # Try whole-output JSON first (Claude Code's preferred shape).
+        begin
+          parsed = JSON.parse(stdout)
+          return parsed.is_a?(Hash) ? parsed : { 'output' => parsed }
+        rescue JSON::ParserError
+          # Fall through to line-delimited scanning.
+        end
+
+        stdout.each_line do |line|
+          stripped = line.strip
+          next if stripped.empty?
+
+          begin
+            parsed = JSON.parse(stripped)
+            return parsed.is_a?(Hash) ? parsed : { 'output' => parsed }
+          rescue JSON::ParserError
+            next
+          end
+        end
+
+        # Non-JSON output: treat as raw output for debugging hooks.
+        { 'output' => stdout }
+      end
+    end
+  end
+end