ask-agent 0.15.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 816f21ed178b31227a58afeeed65f2428dbe9cce7d4a6ddab2c6fda7a6a60a89
-  data.tar.gz: 4dec09ce3cc94c6abc0e94bd5dee9f6ac9bde083dc7995af601a6650e692fd37
+  metadata.gz: cf7561a6eebc134d4e84ba829e637638a783eb7dd425c1b1c24d2d879e5ff47e
+  data.tar.gz: 73cdf03eec1b27f3e50cbfa28399bdf17994ea1b5925be36ce463ebf48c6669d
 SHA512:
-  metadata.gz: 8de0c033834105f7c147115bd84b97306fc91b787690fc9e82563835f53b8fad69ff90dfabeeada12be9a8651e9ecfffd960d8e2fa6e84ffff4709f30519a5de
-  data.tar.gz: b5d46db9e66b242ea35fafaf86c67401ad27ee8ef0099ad4811a3d8442e63bd54aa2b16be5e4a7b2aa0f7305603cf39d1b5497e66648f59a9d701489bbdc6c8c
+  metadata.gz: 37b261bba11ac89e4051b2f631305ed6741ae8ba6a18f0973a2fa7a04416d3dd84d2ca9e4517d01f4776a21fbf143125a51bcceb74b67ce361d9c4ea35e15279
+  data.tar.gz: bc3051e56b9b68a003da46e1ee4c4ec10265239bfc2482c6cc335caf510f099256e1487526ead9277687004a0bb4c68926efb9f51db338b103f69188f21ed60a

data/CHANGELOG.md

@@ -1,4 +1,147 @@
-## [0.15.0] — 2026-07-24
+## [0.23.0] — 2026-07-30
+
+### Added
+
+- **`Ask::Agent::Configuration#default_provider` — global default provider**.
+  Pins which provider serves the default model when the model id is
+  registered under multiple providers (e.g. the same model on several
+  OpenAI-compatible endpoints). `Chat#build_provider` falls back to the
+  global default before the model's own catalog entry. A per-chat
+  `provider:` override or a Definition-level `provider` always wins.
+
+## [0.22.0] — 2026-07-26
+
+### Added
+
+- **`Ask::Agent::Extensions::AuditLog` — event-driven audit logging with pluggable adapters**.
+  Subscribes to all session events and writes them to a configurable adapter.
+  Ships with two built-in adapters:
+
+  - **`FileAdapter`** — appends JSON lines to a file (development/quick-start)
+  - **`ActiveRecordWriter`** — writes to an `ask_audit_logs` table, auto-creates it
+    on first write using `CREATE TABLE IF NOT EXISTS`. Works with or without Rails
+    migrations.
+
+  ```ruby
+  # Global config (all sessions)
+  Ask::Agent.configure { |c| c.audit_log = { adapter: :active_record } }
+
+  # Per-session
+  session = Ask::Agent::Session.new(model: "gpt-4o", audit_log: { adapter: :file })
+  ```
+
+  Events logged: `session_start`, `session_end`, `turn_end`, `tool_execution_start`,
+  `tool_execution_end`, `error`, `max_turns_exceeded`, `loop_detected`,
+  `compaction_end`, `evaluation_blocked`.
+
+  Sensitive arguments (password, token, api_key, sql, etc.) are redacted automatically.
+
+- **12 tests** for AuditLog — adapter contract, event subscription, config integration,
+  sensitive arg redaction, legacy hook interface.
+
+### Changed
+
+- `Session#initialize` now accepts `audit_log:` parameter and falls back to
+  `Ask::Agent.configuration.audit_log`.
+- `Ask::Agent::Configuration#audit_log` — new accessor for global audit log config.
+
+## [0.21.0] — 2026-07-26
+
+- Version bump only.
+
+## [0.20.0] — 2026-07-26
+
+### Added
+
+- **`Events::ThinkingDelta`** — new event emitted when a chunk has thinking/reasoning
+  content. The loop already received chunks with `.thinking` data from providers like
+  DeepSeek and Claude, but it wasn't exposed as a dedicated event. Now it is.
+- **`Ask::Agent::Streaming`** — framework-agnostic SSE streaming module. Returns a
+  Rack-compatible Enumerator that yields SSE-formatted strings as the agent runs.
+  Works with any Rack server without requiring Rails or ActionController::Live.
+
+  Two modes:
+  - **Enumerable mode** (no block) — for Rack/Roda/Sinatra:
+    ```ruby
+    stream = Ask::Agent::Streaming.run(session, prompt)
+    [200, { "Content-Type" => "text/event-stream" }, stream]
+    ```
+  - **Block mode** — for Rails `ActionController::Live::SSE`:
+    ```ruby
+    Ask::Agent::Streaming.run(session, prompt) do |type, data|
+      sse.write(data, event: type)
+    end
+    ```
+
+- **19 tests** for Streaming + ThinkingDelta — Enumerator mode, block mode, custom
+  event maps, error handling, SSE line format, event structure.
+
+## [0.19.0] — 2026-07-26
+
+### Added
+
+- **`Ask::Agent::SubAgent.new("definition_name")` — create sub-agents from
+  filesystem definitions**. Passing a string looks up an agent definition
+  by name (same convention as `Ask::Agent.new("name")`), reading model,
+  tools, instructions, and other settings from the definition files.
+
+  ```ruby
+  # agents/web_search/agent.rb defines model, tools, instructions
+  search = Ask::Agent::SubAgent.new("web_search")
+
+  coordinator = Ask::Agent::Session.new(
+    model: "gpt-4o",
+    tools: [search, Ask::Tools::Shell::Bash]
+  )
+  ```
+
+- **VCR-based integration tests** for SubAgent. Real API calls are recorded
+  and replayed via VCR cassettes. Run with `OPENAI_API_KEY` set to record,
+  or without to replay existing cassettes.
+
+### Changed
+
+- `Ask::Agent::SubAgent.new(name:, ...)` now supports `provider:` parameter
+  for provider-specific sub-agents.
+
+## [0.18.0] — 2026-07-26
+
+### Added
+
+- **`Ask::Agent::SubAgent` — delegate tasks to a specialized sub-agent tool**.
+  A self-contained tool class that satisfies the tool duck type (`name`,
+  `description`, `params_schema`, `call`). When the coordinator LLM calls it,
+  a fresh sub-agent session runs independently with its own model, tools,
+  and instructions.
+
+  ```ruby
+  search = Ask::Agent::SubAgent.new(
+    name: "web_search",
+    description: "Search the web for current information",
+    model: "gpt-4o-mini",
+    tools: [MyApp::Tools::WebSearch],
+    system_prompt: "You are a research assistant."
+  )
+
+  coordinator = Ask::Agent::Session.new(
+    model: "gpt-4o",
+    tools: [search, Ask::Tools::Shell::Bash]
+  )
+
+  coordinator.run("What's the latest Rails release and how stable is it?")
+  ```
+
+### Removed
+
+- **`Ask::Agent.sub_agent_tool`** factory method — replaced by the
+  `Ask::Agent::SubAgent` class directly. The class IS the tool, no
+  factory or wrapper needed.
+
+## [0.17.0] — 2026-07-26
+
+### Added
+
+- Bump ask-tools dependency for `Ask::Tools::SubAgent` support
 
 ### Added
 

data/README.md

@@ -218,6 +218,7 @@ c.middleware.use :model_fallback,
 ```ruby
 Ask::Agent.configure do |c|
   c.default_model = "claude-sonnet-4"
+  c.default_provider = :anthropic
   c.default_max_turns = 50
   c.compactor_enabled = true
   c.compactor_threshold = 0.8
@@ -226,6 +227,12 @@ Ask::Agent.configure do |c|
 end
 ```
 
+`default_provider` pins which provider serves the default model when the
+model name doesn't uniquely identify one (for example, the same model id
+registered under multiple OpenAI-compatible providers). A `provider:`
+passed to `Session.new` or declared in an agent `Definition` always wins
+over the global default.
+
 ## Persistence
 
 ```ruby

data/lib/ask/agent/chat.rb

@@ -19,7 +19,7 @@ module Ask
     ToolCallInfo = Data.define(:id, :name, :arguments)
 
     ChatChunk = Data.define(:content, :tool_calls, :thinking, :input_tokens, :output_tokens) do
-      def tool_call? = !tool_calls.empty?
+      def tool_call? = !tool_calls.to_a.empty?
     end
 
     class Chat
@@ -68,7 +68,8 @@ module Ask
           metadata: {
             input_tokens: response_msg.input_tokens,
             output_tokens: response_msg.output_tokens,
-            cost: response_msg.cost
+            cost: response_msg.cost,
+            thinking: response_msg.thinking
           }.compact
         )
 
@@ -115,7 +116,7 @@ module Ask
       end
 
       def build_provider
-        slug = @provider_override&.to_s || @model_info.provider
+        slug = @provider_override&.to_s || Ask::Agent.configuration.default_provider&.to_s || @model_info.provider
         klass = Ask::Provider.resolve(slug)
         klass.new(provider_config(slug))
       end
@@ -255,12 +256,17 @@ module Ask
       def accumulate_tool_calls(raw_chunk, calls_acc)
         return unless raw_chunk.tool_call?
 
-        raw_chunk.tool_calls.each do |tc|
-          idx = tc[:index] || 0
-          calls_acc[idx] ||= { id: tc[:id], name: tc[:name], arguments: +"" }
-          calls_acc[idx][:id] ||= tc[:id]
-          calls_acc[idx][:name] ||= tc[:name]
-          calls_acc[idx][:arguments] << tc[:arguments].to_s if tc[:arguments]
+        tool_calls = raw_chunk.tool_calls
+        return unless tool_calls.respond_to?(:each)
+
+        tool_calls.each do |tc|
+          next unless tc.respond_to?(:[])
+          idx = tc[:index] || tc["index"] || 0
+          calls_acc[idx] ||= { id: tc[:id] || tc["id"], name: tc[:name] || tc["name"], arguments: +"" }
+          calls_acc[idx][:id] ||= tc[:id] || tc["id"]
+          calls_acc[idx][:name] ||= tc[:name] || tc["name"]
+          arguments = tc[:arguments] || tc["arguments"]
+          calls_acc[idx][:arguments] << arguments.to_s if arguments
         end
       end
 
@@ -279,14 +285,21 @@ module Ask
 
       def build_tool_call_hash(raw_calls)
         hash = {}
+        return hash unless raw_calls.respond_to?(:each)
+
         raw_calls.each do |tc|
-          id = tc[:id] || tc["id"]
-          next unless id
-          hash[id] = ToolCallInfo.new(
-            id: id,
-            name: tc[:name] || tc["name"] || "",
-            arguments: tc[:arguments] || tc["arguments"] || ""
-          )
+          # Provider tool calls come as an Array of Hashes.
+          # A Hash argument (key-value pairs) means the caller passed
+          # a Hash instead of an Array — iterate values instead.
+          if tc.is_a?(Hash)
+            id = tc[:id] || tc["id"]
+            next unless id
+            hash[id] = ToolCallInfo.new(
+              id: id,
+              name: tc[:name] || tc["name"] || "",
+              arguments: tc[:arguments] || tc["arguments"] || ""
+            )
+          end
         end
         hash
       end
@@ -298,7 +311,7 @@ module Ask
           content: stream.accumulated_text,
           tool_calls: build_current_tool_calls(calls_acc),
           tool_results: {},
-          thinking: stream.chunks.filter_map(&:thinking).last,
+          thinking: stream.chunks.filter_map(&:thinking).join,
           input_tokens: tokens[:input],
           output_tokens: tokens[:output],
           cost: cost

data/lib/ask/agent/configuration.rb

@@ -3,9 +3,10 @@
 module Ask
   module Agent
     class Configuration
-      attr_accessor :default_model, :default_max_turns, :compactor_enabled,
-                    :compactor_threshold, :parallel_tool_execution, :max_tool_retries,
-                    :prompt_caching, :default_evaluator_model
+      attr_accessor :default_model, :default_provider, :default_max_turns,
+                    :compactor_enabled, :compactor_threshold, :parallel_tool_execution,
+                    :max_tool_retries, :prompt_caching, :default_evaluator_model,
+                    :audit_log
 
       # @return [Middleware::Pipeline] the middleware pipeline for provider calls
       attr_reader :middleware

data/lib/ask/agent/events.rb

@@ -11,6 +11,7 @@ module Ask
 
       MessageStart = Data.define
       TextDelta = Data.define(:content)
+      ThinkingDelta = Data.define(:content)
       ToolCallDelta = Data.define(:name, :arguments, :id)
       MessageEnd = Data.define(:tool_calls)
 

data/lib/ask/agent/extensions/audit_log/active_record_writer.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    module Extensions
+      class AuditLog
+        # ActiveRecord adapter for the audit log.
+        # Auto-creates the +ask_audit_logs+ table on first write using
+        # CREATE TABLE IF NOT EXISTS, so it works with or without Rails
+        # migrations. Rails users can also run:
+        #
+        #   rails generate ask_rails:install
+        #
+        # to get a proper migration file. The migration uses
+        # +if_not_exists: true+ so it won't conflict with auto-creation.
+        class ActiveRecordWriter < Adapter
+          TABLE_NAME = "ask_audit_logs"
+
+          def initialize
+            @table_checked = false
+            @mutex = Mutex.new
+          end
+
+          def write(entry)
+            return unless defined?(ActiveRecord::Base)
+
+            ensure_table!
+            conn = ActiveRecord::Base.connection
+            conn.execute(
+              "INSERT INTO #{TABLE_NAME} (session_id, event_type, data, timestamp, created_at, updated_at) " \
+              "VALUES (#{quote(entry[:session_id])}, #{quote(entry[:event_type])}, " \
+              "#{quote(entry[:data].to_json)}, #{quote(entry[:timestamp])}, " \
+              "#{quote(Time.now.utc.iso8601(3))}, #{quote(Time.now.utc.iso8601(3))})"
+            )
+          rescue ActiveRecord::ActiveRecordError => e
+            warn "[ask-agent] AuditLog::ActiveRecordWriter write failed: #{e.message}"
+          end
+
+          private
+
+          def ensure_table!
+            return if @table_checked
+
+            @mutex.synchronize do
+              return if @table_checked
+              conn = ActiveRecord::Base.connection
+              unless conn.table_exists?(TABLE_NAME)
+                conn.create_table(TABLE_NAME, if_not_exists: true) do |t|
+                  t.string :session_id, null: false
+                  t.string :event_type, null: false
+                  t.jsonb :data, default: {}
+                  t.datetime :timestamp, null: false
+                  t.timestamps
+
+                  t.index [:session_id, :event_type]
+                  t.index :timestamp
+                end
+              end
+              @table_checked = true
+            end
+          end
+
+          def quote(value)
+            ActiveRecord::Base.connection.quote(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/extensions/audit_log.rb

@@ -1,40 +1,187 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Ask
   module Agent
     module Extensions
+      # Event-driven audit log for agent sessions.
+      #
+      # Subscribes to all session events and writes them to a configurable
+      # adapter. Ships with an ActiveRecord adapter; custom adapters can
+      # implement the simple {Adapter} interface.
+      #
+      # @example Enable globally (ActiveRecord)
+      #   Ask::Agent.configure do |c|
+      #     c.audit_log = { adapter: :active_record }
+      #   end
+      #
+      # @example Per-session with custom adapter
+      #   Session.new(model: "gpt-4o", audit_log: { adapter: MyWriter.new })
+      #
       class AuditLog
-        def initialize(output: $stdout, path: nil)
-          @entries = []
-          @mutex = Mutex.new
+        # Pluggable adapter interface.
+        # Implement +write(entry)+ to persist a structured event hash.
+        class Adapter
+          def write(entry)
+            raise NotImplementedError
+          end
+        end
 
-          if path
-            @io = File.open(path, "a")
-            @io.sync = true
-          else
-            @io = output
+        # Built-in adapter: appends JSON lines to a file.
+        class FileAdapter < Adapter
+          def initialize(path: "tmp/agent_audit.jsonl")
+            @path = path
+            @mutex = Mutex.new
+          end
+
+          def write(entry)
+            @mutex.synchronize do
+              File.open(@path, "a") { |f| f.puts(JSON.generate(entry)) }
+            end
+          end
+        end
+
+        # Event types that get persisted (not every delta/stream event).
+        STORED_EVENTS = {
+          Events::SessionStart       => "session_start",
+          Events::SessionEnd         => "session_end",
+          Events::TurnEnd            => "turn_end",
+          Events::ToolExecutionStart => "tool_execution_start",
+          Events::ToolExecutionEnd   => "tool_execution_end",
+          Events::Error              => "error",
+          Events::MaxTurnsExceeded   => "max_turns_exceeded",
+          Events::LoopDetected       => "loop_detected",
+          Events::CompactionEnd      => "compaction_end",
+          Events::EvaluationBlocked  => "evaluation_blocked"
+        }.freeze
+
+        def initialize(session, adapter: nil)
+          @session = session
+          @session_id = session.id
+          @adapter = resolve(adapter)
+          subscribe! if @adapter
+        end
+
+        # Subscribe to session events and log stored event types.
+        def subscribe!
+          @session.on_event do |event|
+            type = STORED_EVENTS[event.class]
+            next unless type
+
+            write_entry(type, extract(event))
           end
         end
 
+        # Legacy hook interface — kept for backward compatibility.
+        # Called by the hooks system after each tool execution.
         def after_tool_call(tool_call, result, _context)
-          entry = {
-            timestamp: Time.now.utc.iso8601(3),
+          write_entry("tool_call", {
             tool_name: tool_call.name,
             arguments: tool_call.arguments,
-            result: result,
-            duration: result[:duration_ms]
-          }
+            result: result&.to_s&.to_s[0, 500],
+            duration_ms: result[:duration_ms]
+          })
+        end
 
-          @mutex.synchronize do
-            @entries << entry
-            @io.puts entry.to_json
-          end
+        private
 
+        def resolve(adapter)
+          return nil if adapter.nil?
+          return adapter if adapter.is_a?(Adapter)
+
+          case adapter
+          when :active_record
+            require "ask/agent/extensions/audit_log/active_record_writer"
+            AuditLog::ActiveRecordWriter.new
+          when Hash
+            resolve(adapter[:adapter] || adapter[:writer])
+          when Symbol, String
+            # Try to load adapter by convention:
+            # :active_record → ask/agent/extensions/audit_log/active_record_writer
+            name = adapter.to_s
+            begin
+              require "ask/agent/extensions/audit_log/#{name}_writer"
+              klass_name = name.split("_").map(&:capitalize).join
+              klass = AuditLog.const_get(klass_name)
+              klass.new
+            rescue LoadError
+              warn "[ask-agent] AuditLog: adapter not found: #{name}"
+              nil
+            end
+          else
+            adapter
+          end
+        rescue LoadError
+          warn "[ask-agent] AuditLog: ActiveRecord adapter not available"
           nil
         end
 
-        def entries
-          @mutex.synchronize { @entries.dup }
+        def write_entry(type, data)
+          entry = {
+            session_id: @session_id,
+            event_type: type,
+            timestamp: Time.now.utc.iso8601(3),
+            data: data
+          }
+          @adapter.write(entry)
+        rescue => e
+          warn "[ask-agent] AuditLog write failed: #{e.message}"
+        end
+
+        def extract(event)
+          case event
+          when Events::SessionStart
+            {}
+          when Events::SessionEnd
+            {
+              turn_count: event.turn_count,
+              tool_calls_made: event.tool_calls_made,
+              input_tokens: event.input_tokens,
+              output_tokens: event.output_tokens,
+              cost: event.cost
+            }
+          when Events::TurnEnd
+            {
+              turn_number: event.turn_number,
+              tool_results_count: event.tool_results&.length || 0,
+              input_tokens: event.input_tokens,
+              output_tokens: event.output_tokens,
+              cost: event.cost
+            }
+          when Events::ToolExecutionStart
+            { name: event.name, id: event.id, args: safe_args(event.arguments) }
+          when Events::ToolExecutionEnd
+            {
+              name: event.name, id: event.id,
+              duration_ms: event.duration_ms,
+              is_error: event.is_error,
+              result: event.result&.to_s&.to_s[0, 500]
+            }
+          when Events::Error
+            { message: event.error, recoverable: event.recoverable }
+          when Events::MaxTurnsExceeded
+            { max_turns: event.max_turns }
+          when Events::LoopDetected
+            { tool_name: event.tool_name, repeated_count: event.repeated_count }
+          when Events::CompactionEnd
+            { tokens_before: event.tokens_before, tokens_after: event.tokens_after }
+          when Events::EvaluationBlocked
+            { feedback: event.feedback, scores: event.scores }
+          else
+            {}
+          end
+        end
+
+        def safe_args(args)
+          return {} unless args.is_a?(Hash)
+
+          safe = args.dup
+          %w[password secret token api_key key auth_token access_token sql command].each do |sensitive|
+            safe[sensitive] = "[REDACTED]" if safe.key?(sensitive)
+            safe[sensitive.to_sym] = "[REDACTED]" if safe.key?(sensitive.to_sym)
+          end
+          safe
         end
       end
     end

data/lib/ask/agent/loop.rb

@@ -27,11 +27,18 @@ module Ask
             event_emitter.emit(Events::TextDelta.new(content: chunk.content))
           end
 
+          if chunk.respond_to?(:thinking) && chunk.thinking.to_s.strip.length > 0
+            event_emitter.emit(Events::ThinkingDelta.new(content: chunk.thinking))
+          end
+
           if chunk.tool_call?
-            chunk.tool_calls.each do |id, tc|
-              event_emitter.emit(Events::ToolCallDelta.new(
-                name: tc.name, arguments: tc.arguments, id: tc.id
-              ))
+            calls = chunk.tool_calls
+            if calls.respond_to?(:each)
+              calls.each do |id, tc|
+                event_emitter.emit(Events::ToolCallDelta.new(
+                  name: tc.name, arguments: tc.arguments, id: tc.id
+                ))
+              end
             end
           end
         end

data/lib/ask/agent/session.rb

@@ -21,7 +21,7 @@ module Ask
                      compactor: nil, hooks: {}, state: nil, persistence: nil,
                      id: nil, system_prompt: nil, parallel_tools: true,
                      reflector: nil, telemetry: true, meta_agent: nil,
-                     agent_dir: nil, evaluator: nil, **chat_options)
+                     agent_dir: nil, evaluator: nil, audit_log: nil, **chat_options)
         @id = id || SecureRandom.uuid
         @agent_dir = agent_dir
         @max_turns = max_turns
@@ -47,6 +47,7 @@ module Ask
         @tool_executor = ToolExecutor.new(max_retries: max_tool_retries, parallel: parallel_tools)
         @compactor = compactor ? build_compactor(compactor) : nil
         @hooks = Hooks.new(hooks)
+        @audit_log = build_audit_log(audit_log)
 
         @system_context = build_system_context(system_prompt)
         apply_system_context
@@ -229,6 +230,10 @@ module Ask
           try_auto_meta_agent
         end
 
+        # Capture messages before emitting SessionEnd so event handlers
+        # can access agent.messages during the callback
+        @messages = @chat.messages.dup
+
         emit(Events::SessionEnd.new(
           result: response,
           turn_count: @turn_count,
@@ -237,7 +242,6 @@ module Ask
           output_tokens: @total_output_tokens,
           cost: @total_cost
         ))
-        @messages = @chat.messages.dup
 
         response
       end
@@ -331,6 +335,12 @@ module Ask
 
       private
 
+      def build_audit_log(config)
+          config ||= Ask::Agent.configuration.audit_log
+          return nil unless config
+          Ask::Agent::Extensions::AuditLog.new(self, adapter: config)
+        end
+
       def build_chat(model, system_prompt, tools, **chat_options)
         if model.respond_to?(:ask)
           model

data/lib/ask/agent/streaming.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module Agent
+    # Framework-agnostic SSE streaming for agent sessions.
+    #
+    # Returns a Rack-compatible Enumerator that yields SSE-formatted strings
+    # as the agent runs. Works with any Rack server (Puma, Falcon, etc.)
+    # without requiring ActionController::Live or Rails.
+    #
+    # @example In a Rails controller (with ActionController::Live::SSE)
+    #   def create
+    #     response.headers["Content-Type"] = "text/event-stream"
+    #     sse = SSE.new(response.stream)
+    #
+    #     Ask::Agent::Streaming.run(session, prompt) do |type, data|
+    #       sse.write(data, event: type)
+    #     end
+    #   ensure
+    #     sse&.close
+    #   end
+    #
+    # @example In a Rack app (raw Enumerator)
+    #   stream = Ask::Agent::Streaming.run(session, prompt)
+    #   [200, { "Content-Type" => "text/event-stream" }, stream]
+    #
+    # @example With custom event mapping
+    #   stream = Ask::Agent::Streaming.run(session, prompt) do |event|
+    #     case event
+    #     when Events::TextDelta
+    #       { type: "delta", data: { content: event.content } }
+    #     when Events::ToolExecutionStart
+    #       { type: "tool_start", data: { name: event.name, id: event.id } }
+    #     else
+    #       nil # skip unhandled events
+    #     end
+    #   end
+    module Streaming
+      DEFAULT_EVENT_MAP = {
+        Events::TextDelta => "delta",
+        Events::ThinkingDelta => "thinking",
+        Events::ToolCallDelta => "tool_call_delta",
+        Events::ToolExecutionStart => "tool_start",
+        Events::ToolExecutionUpdate => "tool_update",
+        Events::ToolExecutionEnd => "tool_end",
+        Events::SessionEnd => "done",
+        Events::Error => "error"
+      }.freeze
+
+      class << self
+        # Run an agent session and stream events as SSE-formatted strings.
+        #
+        # Two modes:
+        #
+        # 1. **No block** — returns a Rack-compatible Enumerator that yields
+        #    raw SSE strings: "data: {\"type\":\"delta\",\"content\":\"...\"}\n\n"
+        #
+        # 2. **With block** — calls the block for each event with
+        #    `(event_type_string, data_hash)`. The block is responsible for
+        #    writing/handling the data. This mode is designed for use with
+        #    Rails' `ActionController::Live::SSE#write`.
+        #
+        # @param session [Session] the agent session to run
+        # @param prompt [String] the user's message
+        # @param event_map [Hash<Class, String>] optional custom event-to-type mapping
+        # @yield [type, data] called for each event (only in block mode)
+        # @yieldparam type [String] the SSE event type name
+        # @yieldparam data [Hash] the event data payload
+        # @return [Enumerator, nil] Enumerator in no-block mode, nil in block mode
+        def run(session, prompt, event_map: {}, &block)
+          mapping = DEFAULT_EVENT_MAP.merge(event_map)
+
+          if block
+            run_with_block(session, prompt, mapping, &block)
+            nil
+          else
+            run_with_enumerator(session, prompt, mapping)
+          end
+        end
+
+        private
+
+        def run_with_block(session, prompt, mapping)
+          errors = []
+
+          session.on_event do |event|
+            type = event_type(event, mapping)
+            data = event_data(event)
+            next unless type
+
+            yield(type, data)
+          end
+
+          # Emit start event
+          yield("start", { session_id: session.id })
+
+          session.run(prompt)
+
+          # If errors accumulated during tool execution, emit them
+          errors.each { |err| yield("error", { message: err }) }
+        rescue => e
+          yield("error", { message: e.message })
+        end
+
+        def run_with_enumerator(session, prompt, mapping)
+          Enumerator.new do |yielder|
+            errors = []
+
+            session.on_event do |event|
+              type = event_type(event, mapping)
+              data = event_data(event)
+              next unless type
+
+              yielder << sse_line(type, data)
+            end
+
+            # Emit start event
+            yielder << sse_line("start", { session_id: session.id })
+
+            session.run(prompt)
+
+            errors.each { |err| yielder << sse_line("error", { message: err }) }
+
+            yielder << sse_line("close", {})
+          rescue => e
+            yielder << sse_line("error", { message: e.message })
+          ensure
+            yielder << sse_line("close", {})
+          end
+        end
+
+        def event_type(event, mapping)
+          # Check for a direct class match
+          return mapping[event.class] if mapping.key?(event.class)
+
+          # Check for a superclass match (e.g. ToolExecutionStart is a kind of event)
+          event.class.ancestors.each do |ancestor|
+            return mapping[ancestor] if mapping.key?(ancestor)
+          end
+
+          nil
+        end
+
+        def event_data(event)
+          case event
+          when Events::TextDelta
+            { content: event.content }
+          when Events::ThinkingDelta
+            { content: event.content }
+          when Events::ToolCallDelta
+            { name: event.name, arguments: event.arguments, id: event.id }
+          when Events::ToolExecutionStart
+            { name: event.name, id: event.id, args: safe_args(event.arguments) }
+          when Events::ToolExecutionUpdate
+            { id: event.id, partial_result: event.partial_result.to_s.truncate(200) }
+          when Events::ToolExecutionEnd
+            { name: event.name, id: event.id, duration_ms: event.duration_ms, is_error: event.is_error }
+          when Events::SessionEnd
+            { turn_count: event.turn_count, tool_calls_made: event.tool_calls_made,
+              input_tokens: event.input_tokens, output_tokens: event.output_tokens,
+              cost: event.cost }
+          when Events::SessionStart
+            {}
+          when Events::Error
+            { message: event.error, recoverable: event.recoverable }
+          else
+            {}
+          end
+        end
+
+        def sse_line(type, data)
+          payload = data.merge(type: type)
+          "data: #{JSON.generate(payload)}\n\n"
+        end
+
+        def safe_args(args)
+          return {} unless args.is_a?(Hash)
+
+          safe = args.dup
+          %w[password secret token api_key key auth_token access_token sql command].each do |sensitive|
+            safe[sensitive] = "[REDACTED]" if safe.key?(sensitive)
+          end
+          safe
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/sub_agent.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    # A tool that delegates a task to a specialized sub-agent.
+    #
+    # The coordinator agent sees this as a regular tool — when the LLM calls it,
+    # a fresh sub-agent session runs independently with its own model, tools,
+    # and instructions, and returns the result.
+    #
+    # Satisfies the tool duck type (name, description, params_schema, call)
+    # so it can be passed directly in the tools array.
+    #
+    # @example From a filesystem definition
+    #   # agents/web_search/agent.rb defines a WebSearch agent.
+    #   # Use it as a sub-agent by passing its name:
+    #
+    #   search = Ask::Agent::SubAgent.new("web_search")
+    #
+    #   coordinator = Ask::Agent::Session.new(
+    #     model: "gpt-4o",
+    #     tools: [search, Ask::Tools::Shell::Bash]
+    #   )
+    #
+    # @example Inline configuration
+    #   search = Ask::Agent::SubAgent.new(
+    #     name: "web_search",
+    #     description: "Search the web for current information",
+    #     model: "gpt-4o-mini",
+    #     tools: [Ask::Tools::WebSearch],
+    #     system_prompt: "You are a research assistant."
+    #   )
+    #
+    # @example Using with a different provider
+    #   review = Ask::Agent::SubAgent.new(
+    #     name: "code_review",
+    #     model: "claude-sonnet-4",
+    #     provider: :anthropic,
+    #     tools: [Ask::Tools::Shell::Read, Ask::Tools::Shell::Grep],
+    #     system_prompt: "You are a senior code reviewer."
+    #   )
+    class SubAgent
+      # @return [String] tool name visible to the LLM
+      attr_reader :name
+
+      # @return [String] tool description visible to the LLM
+      attr_reader :description
+
+      # Create a new SubAgent tool.
+      #
+      # When given a String, looks up a filesystem agent definition by name
+      # (matching the convention used by {Ask::Agent.new}). Model, tools,
+      # instructions, and other settings are read from the definition files.
+      #
+      # When given keyword arguments, configures the sub-agent inline.
+      #
+      # @overload initialize(definition_name)
+      #   @param definition_name [String] Name of a filesystem agent definition.
+      #   @raise [Ask::Agent::UnknownAgent] If no definition is found.
+      #
+      # @overload initialize(name:, description: nil, model:, tools: [],
+      #           system_prompt: nil, provider: nil, max_turns: 10, **session_opts)
+      #   @param name [String] Tool name (e.g. "web_search").
+      #   @param description [String, nil] Tool description. Auto-generated
+      #     from the model and tools count if not provided.
+      #   @param model [String] Model identifier for the sub-agent session.
+      #   @param tools [Array<Class, Object>] Tools available to the sub-agent.
+      #   @param system_prompt [String, nil] Instructions for the sub-agent.
+      #   @param provider [Symbol, nil] Provider override.
+      #   @param max_turns [Integer] Max conversation turns for the sub-agent.
+      #   @param session_opts [Hash] Additional options forwarded to Session.new.
+      def initialize(definition_name = nil, name: nil, description: nil, model: nil,
+                     tools: [], system_prompt: nil, provider: nil,
+                     max_turns: 10, **session_opts)
+        if definition_name
+          from_definition(definition_name, **session_opts)
+        else
+          @name = name
+          @description = description || default_description(model, tools)
+          @model = model
+          @tools = tools.map { |t| t.is_a?(Class) ? t.new : t }
+          @system_prompt = system_prompt
+          @provider = provider
+          @max_turns = max_turns
+          @session_opts = session_opts
+        end
+      end
+
+      # JSON Schema for the tool's parameter.
+      #
+      # @return [Hash]
+      def params_schema
+        {
+          type: "object",
+          properties: {
+            "task" => {
+              type: "string",
+              description: "The task to delegate to the sub-agent"
+            }
+          },
+          required: ["task"],
+          additionalProperties: false
+        }
+      end
+
+      # Provider-specific parameters (none by default).
+      #
+      # @return [Hash]
+      def provider_params
+        {}
+      end
+
+      # Execute the sub-agent with the given task.
+      #
+      # Creates a fresh session for each call, runs the task, and returns the
+      # result. If the sub-agent fails, returns an error result — the
+      # coordinator can decide how to proceed.
+      #
+      # @param args [Hash, String] Arguments from the LLM.
+      # @param abort_controller [Object, nil] Optional abort controller.
+      # @return [Ask::Result]
+      def call(args = {}, abort_controller = nil)
+        task = extract_task(args)
+
+        session_opts = {
+          model: @model,
+          tools: @tools.map(&:class),
+          max_turns: @max_turns
+        }
+        session_opts[:provider] = @provider if @provider
+        session_opts[:system_prompt] = @system_prompt if @system_prompt
+        session_opts.merge!(@session_opts)
+
+        session = Session.new(**session_opts)
+        result = session.run(task.to_s)
+        Ask::Result.ok(data: result.to_s)
+      rescue StandardError => e
+        Ask::Result.failure("SubAgent '#{@name}' error: #{e.message}")
+      end
+
+      # Human-readable representation.
+      #
+      # @return [String]
+      def inspect
+        "#<Ask::Agent::SubAgent name=#{@name.inspect}>"
+      end
+
+      private
+
+      def from_definition(definition_name, **session_opts)
+        Ask::Agent.rediscover!
+        entry = Ask::Agent.definitions[definition_name.to_s]
+        raise UnknownAgent, "Unknown agent: #{definition_name.inspect}" unless entry
+
+        klass, dir = entry
+        config = klass._config
+
+        @name = definition_name
+        @model = config[:model]
+        @description = "Delegate to #{definition_name} sub-agent (#{@model})"
+        @provider = config[:provider]
+
+        # Resolve tools from definition
+        resolved_tools = Ask::Agent.__send__(:resolve_definition_tools, config[:tools] || [], dir)
+        @tools = resolved_tools.map { |t| t.is_a?(Class) ? t.new : t }
+
+        # Load instructions from definition
+        prompt = klass.instructions_content
+        @system_prompt = prompt
+
+        @max_turns = config[:max_turns] || 10
+        # Merge any options from the definition config
+        @session_opts = (config[:options] || {}).merge(session_opts)
+      end
+
+      def extract_task(args)
+        case args
+        when Hash then (args["task"] || args[:task] || args.to_s).to_s
+        else args.to_s
+        end
+      end
+
+      def default_description(model, tools)
+        desc = "Delegate to a sub-agent (#{model}"
+        desc += " with #{tools.size} tool(s)" if tools.any?
+        desc + ")"
+      end
+    end
+  end
+end

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.15.0"
+    VERSION = "0.23.0"
   end
 end

data/lib/ask/agent.rb

@@ -7,6 +7,7 @@ require "time"
 require "ask/skills"
 require "ask-llm-providers"
 require "ask-tools"
+require "ask-state-providers"
 
 module Ask
   module Agent
@@ -244,6 +245,29 @@ require_relative "agent/skills/load_skill_tool"
 require_relative "agent/scheduler"
 require_relative "agent/definition"
 require_relative "agent/cli"
+require_relative "agent/streaming"
+require_relative "agent/sub_agent"
 
 # Test helpers (loaded on demand)
 autoload :Test, "ask/agent/test"
+
+# Convenience method on the top-level Ask module.
+# Provides a quick one-shot chat without instantiating a Session directly.
+#
+#   Ask.chat("Hello")
+#   Ask.chat("Tell me about X", model: "gpt-4o")
+#   Ask.chat("Stream this") { |chunk| puts chunk.content }
+#
+module Ask
+  def self.chat(message, model: nil, system_prompt: nil, &block)
+    session = Agent::Session.new(
+      model: model || Agent.configuration.default_model,
+      system_prompt: system_prompt
+    )
+    if block
+      session.run(message, &block)
+    else
+      session.run(message)
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.23.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -174,6 +174,7 @@ files:
 - lib/ask/agent/evaluator.rb
 - lib/ask/agent/events.rb
 - lib/ask/agent/extensions/audit_log.rb
+- lib/ask/agent/extensions/audit_log/active_record_writer.rb
 - lib/ask/agent/extensions/permissions.rb
 - lib/ask/agent/extensions/rate_limiter.rb
 - lib/ask/agent/hooks.rb
@@ -196,6 +197,8 @@ files:
 - lib/ask/agent/stream_transforms/pipeline.rb
 - lib/ask/agent/stream_transforms/text_buffer.rb
 - lib/ask/agent/stream_transforms/thinking_separator.rb
+- lib/ask/agent/streaming.rb
+- lib/ask/agent/sub_agent.rb
 - lib/ask/agent/system_context.rb
 - lib/ask/agent/telemetry.rb
 - lib/ask/agent/test.rb