ask-decisions 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09c0d2c768b78986cc452b899fca0579c7030fe8d4e9b067dcc6d38b8aebe544'
-  data.tar.gz: 6af44122d2741d29f5897c655cba0f38e99596dff88fec8152a95237957d514f
+  metadata.gz: 3dd4560892d89a85e39ed1e73474268724f2f55fca39f1471e9e490e2044168c
+  data.tar.gz: d960989693373e6ce7afe0ddcec17bc88e59addafb89d5269fa67ef52bb9b299
 SHA512:
-  metadata.gz: fd023d73dd39cffa709fbf27f651dfddfe39590bc77ca6874eac5d2c85fe10e8bcc3b1df51757eb6d612df6fde8f1691ad1cb704c74b26ace67349c845b6e8c3
-  data.tar.gz: ef8451ad571c3d52d20b17641ddee5a01e24ae39ea1e7a1e976ab0743dd375d2775f27d569b4cc451111df9543359a2bd00ce0f4ef5cc40ee8ce2cb3cdefeb14
+  metadata.gz: 3e2616a2e442dd2c764e5dd3d020a7ba7086f40ba24acca442e272db358817727e4bbaa6c57e84b87fea7c3e64103a6c6a741d7cac24f29f72504708a086b6ea
+  data.tar.gz: 99ea57a135e7f4265245f246f908af5b821b4780ffbf9cafe8f68c94c9d63124e4298666b106c556ccbb9c9aa1be75bb45e690747f9c063fc1616ee053553248

data/CHANGELOG.md

@@ -4,7 +4,39 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [0.2.0] - 2026-09-18
+## [0.2.1] - 2026-09-17
+
+### Added
+
+- **The host owns the judgement: `Gate.new(provider, questions:, thresholds:)`.**
+  The questions a gate asks are a property of the host's tools, not of the gem.
+  A booking tool and a shell tool are not dangerous for the same reason, and
+  pi-jev's questions — "is this action destructive?", "does this send local data
+  off-machine?" — say nothing useful about booking an appointment. A host now
+  asks its own: "does this commit the customer to a booking?", "does this spend
+  the owner's money?". Every question must be armed with a threshold, and a
+  question without one is refused at construction rather than armed with a bar
+  that never fires. A threshold given for one of the default questions still
+  keeps the rest of the defaults, so raising one bar stays one line.
+
+- **`OutputJudge.new(provider, questions:, advice:)`.** Same reasoning: what an
+  output *is* — a leak, a failure class, the advice to give — belongs to the
+  host. The two ids the result reads (`:leaks_secret`, `:failure_class`) stay
+  the gem's contract, and the outcome question must offer `no_failure` among its
+  criteria, because the judge runs after every judged call and not only after a
+  suspicious one; both are refused at construction when they are missing, since
+  a judge that reads nothing judges nothing, silently.
+
+- **`AgentAdapter` passes the judgement through** — `gate_questions`,
+  `output_questions`, `output_advice` — so a host configures the guards for its
+  own tools in one place.
+
+### Notes
+
+- 0.2.0 is what it was released as: the router removal below, and the
+  host-owned judgement arrived after it.
+
+## [0.2.0] - 2026-09-17
 
 ### Removed
 

data/lib/ask/decisions/agent_adapter.rb

@@ -106,12 +106,25 @@ module Ask
         Ask::Decisions.resolve_provider(name)
       end
 
+      # What the host judges, and how high the bar is. The questions are the
+      # host's because risk is: a booking tool and a shell tool are not
+      # dangerous for the same reason, and a gate written for one says nothing
+      # useful about the other.
       def gate_config
-        { tools: @config[:gate_tools], thresholds: @config[:gate_thresholds] || {} }.compact
+        {
+          questions: @config[:gate_questions],
+          thresholds: @config[:gate_thresholds],
+          tools: @config[:gate_tools]
+        }.compact
       end
 
       def output_judge_config
-        { tools: @config[:output_tools], output_limit: @config[:output_limit] }.compact
+        {
+          questions: @config[:output_questions],
+          advice: @config[:output_advice],
+          tools: @config[:output_tools],
+          output_limit: @config[:output_limit]
+        }.compact
       end
 
       def failure_classifier_config

data/lib/ask/decisions/gate.rb

@@ -49,11 +49,20 @@ module Ask
       }.freeze
 
       # @param provider [Ask::DecisionProvider] the decision provider to use
-      # @param thresholds [Hash] override specific thresholds
+      # @param questions [Hash{Symbol => Decision::Noul,Decision::Score}] what
+      #   to ask about a call. The defaults above are pi-jev's, written for a
+      #   coding agent's tools; a host with other tools should say what risk
+      #   means for them ("does this commit the customer to a booking?", "does
+      #   this spend the owner's money?") rather than inherit a vocabulary
+      #   about shell commands.
+      # @param thresholds [Hash{Symbol => Numeric}] the bar for each question.
+      #   Every question needs one: a question with no threshold can never
+      #   flag, and a gate that looks armed and never fires is worse than none.
       # @param tools [Array<String>, nil] tools to gate (nil = all)
-      def initialize(provider, thresholds: {}, tools: nil)
+      def initialize(provider, questions: QUESTIONS, thresholds: DEFAULT_THRESHOLDS, tools: nil)
         @provider = provider
-        @thresholds = DEFAULT_THRESHOLDS.merge(thresholds)
+        @questions = questions
+        @thresholds = arming_thresholds(questions, thresholds)
         @tools = tools
       end
 
@@ -71,7 +80,7 @@ module Ask
 
         result = @provider.evaluate(
           state: state,
-          decisions: QUESTIONS
+          decisions: @questions
         )
 
         Verdict.new(result, @thresholds)
@@ -79,6 +88,27 @@ module Ask
 
       private
 
+      # Every question must be armed. A host that supplies its own questions
+      # and forgets a threshold would otherwise get a gate that silently
+      # ignores one of its own risk questions, which is the failure mode a
+      # gate exists to prevent.
+      #
+      # A threshold given for a question the defaults also ask keeps the rest
+      # of the defaults, so raising one bar is one line rather than a copy of
+      # the table.
+      def arming_thresholds(questions, thresholds)
+        keys = questions.keys.map(&:to_sym)
+        armed = DEFAULT_THRESHOLDS.slice(*keys).merge(thresholds.to_h.transform_keys(&:to_sym))
+        unarmed = keys - armed.keys
+
+        unless unarmed.empty?
+          raise ArgumentError,
+            "no threshold for #{unarmed.inspect}: a question that cannot fire is not a gate"
+        end
+
+        armed
+      end
+
       def build_state(tool:, args:, working_dir: nil, user_message: nil)
         {
           tool: tool,

data/lib/ask/decisions/output_judge.rb

@@ -46,12 +46,35 @@ module Ask
       }.freeze
 
       # @param provider [Ask::DecisionProvider]
-      # @param tools [Array<String>, nil] tools to judge (nil = ["bash"])
+      # The class that means nothing went wrong. A host's outcome question has
+      # to offer it, because the judge runs after every judged call and not
+      # only after a suspicious one: without it, every successful call would
+      # read as a failure.
+      SUCCESS_CLASS = "no_failure"
+
+      # A host judges two things about an output: whether it leaked something
+      # (`:leaks_secret`), and what happened (`:failure_class`). Those two ids
+      # are the gem's contract and stay fixed; the questions' words, the
+      # classes they can answer with, and the advice per class are the host's —
+      # a coding agent's failures are code bugs and broken environments, a
+      # business's are "we don't offer that" and "the system is down".
+      #
+      # @param questions [Hash{Symbol => Decision}] what to ask about a result.
+      #   Must answer under :leaks_secret and :failure_class, and the outcome
+      #   question must offer the class above among its criteria.
+      # @param advice [Hash{String => String,nil}] one line per class the
+      #   outcome question can answer with. A class with no line is advice the
+      #   model does not get.
+      # @param tools [Array<String>, nil] tools to judge (nil = the gem's own
+      #   default, the coding agent's shell tool — pass the host's own)
       # @param leak_threshold [Float] noul threshold for leak detection
       # @param failure_threshold [Float] confidence threshold for failure classification
       # @param output_limit [Integer] max characters of output to send
-      def initialize(provider, tools: nil, leak_threshold: 0.90, failure_threshold: 0.60, output_limit: 2000)
+      def initialize(provider, questions: QUESTIONS, advice: ADVICE, tools: nil,
+        leak_threshold: 0.90, failure_threshold: 0.60, output_limit: 2000)
         @provider = provider
+        @questions = judgeable(questions)
+        @advice = advice
         @tools = tools || ["bash"]
         @leak_threshold = leak_threshold
         @failure_threshold = failure_threshold
@@ -70,12 +93,32 @@ module Ask
         truncated = truncate(output, @output_limit)
         state = { output: truncated, tool_arguments: truncate_values(args, 400) }
 
-        result = @provider.evaluate(state: state, decisions: QUESTIONS)
-        OutputResult.new(result, @leak_threshold, @failure_threshold)
+        result = @provider.evaluate(state: state, decisions: @questions)
+        OutputResult.new(result, @leak_threshold, @failure_threshold, advice: @advice)
       end
 
       private
 
+      # A host's questions have to answer the two things the result reads, and
+      # the outcome question has to be able to say that nothing went wrong.
+      # Both are silent failures otherwise — a judge that reads nothing judges
+      # nothing — so they are refused at construction instead.
+      def judgeable(questions)
+        missing = %i[leaks_secret failure_class] - questions.keys.map(&:to_sym)
+        unless missing.empty?
+          raise ArgumentError, "the output judge needs questions for #{missing.inspect}"
+        end
+
+        criteria = Array(questions[:failure_class].criteria&.keys)
+        unless criteria.include?(SUCCESS_CLASS)
+          raise ArgumentError,
+            "the failure_class question must offer #{SUCCESS_CLASS.inspect} among its criteria, " \
+            "or every successful call reads as a failure"
+        end
+
+        questions
+      end
+
       def truncate(str, limit)
         return "" if str.nil?
         str.length > limit ? "#{str[0, limit]}…[#{str.length - limit} chars elided]" : str
@@ -91,17 +134,17 @@ module Ask
       class OutputResult
         attr_reader :leak_noul, :failure_class, :failure_confidence, :advice
 
-        def initialize(batch, leak_threshold, failure_threshold)
+        def initialize(batch, leak_threshold, failure_threshold, advice: ADVICE)
           leak_answer = batch["leaks_secret"]
           failure_answer = batch["failure_class"]
 
           @leak_noul = leak_answer&.noul || 0.0
           @leak_threshold = leak_threshold
 
-          @failure_class = failure_answer&.choice || "no_failure"
+          @failure_class = failure_answer&.choice || SUCCESS_CLASS
           @failure_confidence = failure_answer&.confidence || 0.0
           @failure_threshold = failure_threshold
-          @advice = ADVICE[@failure_class]
+          @advice = advice[@failure_class]
         end
 
         def leak?
@@ -109,7 +152,7 @@ module Ask
         end
 
         def failure?
-          @failure_class != "no_failure" && @failure_confidence >= @failure_threshold
+          @failure_class != SUCCESS_CLASS && @failure_confidence >= @failure_threshold
         end
 
         def to_s

data/lib/ask/decisions/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Decisions
-    VERSION = "0.2.0"
+    VERSION = "0.2.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-decisions
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Kaka Ruto