rubyn-code 0.5.1 → 0.7.0

data/lib/rubyn_code/goal/evaluator.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module RubynCode
+  # Session goals: a goal is a plain-language condition the user wants
+  # satisfied before the agent stops working. The Goal::Evaluator judges,
+  # via a lightweight LLM call, whether the condition has been met based on
+  # the recent conversation. Used by Hooks::GoalHook on the :stop event.
+  module Goal
+    # Judges whether a goal condition has been satisfied.
+    #
+    # The evaluator is deliberately conservative: it returns true only when
+    # the model is confident the goal is genuinely complete. Any error or
+    # ambiguous answer is treated as "not met" so the agent keeps working
+    # rather than stopping prematurely.
+    class Evaluator
+      SYSTEM_PROMPT = <<~PROMPT
+        You are a strict completion judge. Given a GOAL and a transcript of an
+        AI coding agent's recent work, decide whether the goal is genuinely and
+        fully satisfied. Be conservative: if there is any doubt, or the work is
+        only partially done, answer NO. Answer with exactly one word on the
+        first line: YES or NO. Optionally add a short reason on the next line.
+      PROMPT
+
+      # Number of trailing conversation messages to show the judge.
+      TRANSCRIPT_WINDOW = 12
+
+      # @param llm_client [LLM::Client]
+      def initialize(llm_client:)
+        @llm_client = llm_client
+      end
+
+      # @param condition [String] the goal condition
+      # @param conversation [Agent::Conversation, nil] recent work to judge
+      # @return [Boolean] true only when the goal is confidently complete
+      def call(condition:, conversation: nil)
+        response = @llm_client.chat(
+          messages: [{ role: 'user', content: prompt(condition, conversation) }],
+          system: SYSTEM_PROMPT
+        )
+        verdict_yes?(answer_text(response))
+      rescue StandardError => e
+        RubynCode::Debug.warn("Goal evaluation failed: #{e.message}")
+        false
+      end
+
+      private
+
+      def prompt(condition, conversation)
+        <<~TEXT
+          GOAL:
+          #{condition}
+
+          RECENT WORK:
+          #{transcript(conversation)}
+
+          Is the goal genuinely and fully satisfied? Answer YES or NO.
+        TEXT
+      end
+
+      def transcript(conversation)
+        return '(no work recorded yet)' unless conversation.respond_to?(:messages)
+
+        Array(conversation.messages).last(TRANSCRIPT_WINDOW).map do |msg|
+          "#{msg[:role]}: #{message_text(msg[:content])}"
+        end.join("\n").slice(0, 6000)
+      end
+
+      def message_text(content)
+        case content
+        when String then content
+        when Array
+          content.filter_map { |b| b.is_a?(Hash) ? (b[:text] || b['text']) : nil }.join(' ')
+        else
+          content.to_s
+        end
+      end
+
+      def answer_text(response)
+        if response.respond_to?(:content)
+          Array(response.content).filter_map { |b| b.respond_to?(:text) ? b.text : nil }.join("\n")
+        elsif response.is_a?(Hash)
+          Array(response[:content] || response['content'])
+            .filter_map { |b| b.is_a?(Hash) ? (b[:text] || b['text']) : nil }.join("\n")
+        else
+          response.to_s
+        end
+      end
+
+      def verdict_yes?(text)
+        first = text.to_s.strip.split("\n").first.to_s.strip.upcase
+        first.start_with?('YES')
+      end
+    end
+  end
+end

data/lib/rubyn_code/hooks/event_map.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Hooks
+    # Maps between internal hook event names (snake_case symbols used by the
+    # in-process Hooks::Runner) and the Claude Code hook event names
+    # (CamelCase strings used by external hooks configured in settings.json).
+    #
+    # Internal hooks fire at these 7 sites:
+    #   :pre_tool_use       — agent/tool_processor.rb#execute_tool
+    #   :post_tool_use      — agent/tool_processor.rb#execute_tool
+    #   :pre_llm_call       — agent/llm_caller.rb
+    #   :post_llm_call      — agent/llm_caller.rb
+    #   :stop               — agent/loop.rb#stop_blocked?
+    #   :session_start      — ide/handlers/prompt_handler.rb (IDE)
+    #   :user_prompt_submit — ide/handlers/prompt_handler.rb (IDE)
+    #
+    # External hooks (Claude Code parity) consume these 9 event names:
+    #   PreToolUse, PostToolUse, UserPromptSubmit, SessionStart,
+    #   SessionEnd, Stop, SubagentStop, PreCompact, Notification
+    module EventMap
+      # Internal symbol => external string
+      TO_EXTERNAL = {
+        pre_tool_use: 'PreToolUse',
+        post_tool_use: 'PostToolUse',
+        pre_llm_call: 'PreCompact',
+        post_llm_call: 'Notification',
+        on_session_end: 'SessionEnd',
+        session_start: 'SessionStart',
+        user_prompt_submit: 'UserPromptSubmit',
+        stop: 'Stop',
+        on_subagent_stop: 'SubagentStop'
+      }.freeze
+
+      # External string => internal symbol
+      TO_INTERNAL = TO_EXTERNAL.invert.freeze
+
+      # Every external event name the dispatcher knows about.
+      EXTERNAL_EVENTS = TO_EXTERNAL.values.freeze
+
+      module_function
+
+      # @param internal [Symbol]
+      # @return [String, nil]
+      def external(internal)
+        TO_EXTERNAL[internal.to_sym]
+      end
+
+      # @param external [String, Symbol]
+      # @return [Symbol, nil]
+      def internal(external)
+        TO_INTERNAL[external.to_s]
+      end
+    end
+  end
+end

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)