ask-agent 0.30.1 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf67fcc30605c8d4752a97133a13a7fbe500c32a68c47640552bc30cf6dbea5b
-  data.tar.gz: 638931a8c1c2c5ae0ca5535e9e78e9252910106af9134366a455523925b6d895
+  metadata.gz: ad75fe0e23adeabc49b068df1916a102d7122710dfe5a45471ba68b47864d75c
+  data.tar.gz: 4f7381343e7d63a4d2b4ffe9e70cf93c92ab941ccdf11dad52d6ff65bbe227cb
 SHA512:
-  metadata.gz: 01ca01b502aa5789eef910f50626085bb6675e86dedd435b189b0e928d592ac27c48c145ff5c159580c2a9854528160c86074031dccd971b033b75b6f42bf3fa
-  data.tar.gz: 6bf3ebc3428cf64c8a1ee7e958e45c349669e4eaba92a8bc5d90b522f0b9a47d4f3743570db235b8d9b4e526d3ea470eb1a81795acc6492fd67afda4b59d9b70
+  metadata.gz: 86a1695d69a497b6ec0fd5b57c942084330a70b35b8bf5fd3340db03ce186be98350eec974c1aaec075e4ef30c8b79628d8c3028d3c64fdb288619f27ff58fda
+  data.tar.gz: b771e752c640319a5de1bbe63f9dec8079e62a9f8d371c8e82b90898e9af303528739c62c852f83cda58513296edd4ffe9372e090f189914149ab417d26bb254

data/CHANGELOG.md

@@ -1,3 +1,53 @@
+## [0.32.0] — 2026-08-06
+
+### Added
+
+- **TodoWrite — the model maintains a live task list.** `Session.new(todos:
+  true)` injects a `todo_write` tool backed by a session-scoped
+  `Ask::Agent::TodoList`:
+  - Actions `add` / `update` / `list` / `clear` with `pending`,
+    `in_progress`, `completed`, `blocked` statuses; every result returns
+    the full list so one call both mutates and shows state.
+  - `Events::TodoUpdated` fires with the full list on every change — the
+    contract for live progress rendering (UI kit / app server).
+  - The list is part of the checkpoint snapshot: `rollback!` and `fork`
+    restore it, and `Session.load` re-enables todos automatically.
+- **Plan mode — research first, execute after human approval.** `Session.new(
+  plan_mode: true)` (or `plan_mode: { read_only_tools: [...] }`) starts the
+  session in a research phase where non-read-only tools are blocked
+  (`:block` with a plan-mode reason; the gate runs before user hooks and
+  the approval policy). The model researches, then calls the injected
+  `exit_plan_mode` tool with its plan:
+  - The plan is submitted to a dedicated `Session#plan_queue` and the tool
+    returns a pending result — the agent hands back the interim reply,
+    exactly like the tool-approval flow.
+  - **Approve** → plan mode turns off, `Events::PlanApproved` fires, and a
+    follow-up turn executes the plan. **Reject** → the session stays in
+    plan mode, `Events::PlanRejected` fires, and the rejection feedback
+    reaches the conversation.
+  - Default read-only allowlist: `read`, `glob`, `grep`, `web_search`.
+
+## [0.31.0] — 2026-08-06
+
+### Added
+
+- **Permission rules — persisted allow/ask/deny patterns for tool calls.**
+  `Ask::Agent::Policies::PermissionRules` classifies every call before it
+  executes or prompts, so "approve once, remember the pattern" replaces
+  per-call prompting:
+  - DSL in declaration order (first match wins): `allow`, `ask`, `deny`
+    with a tool pattern (String, Symbol, Regexp, or `:all`) and an optional
+    argument pattern (Regexp, substring, or `nil` for any).
+  - Wire in via `Session.new(approval: { rules: rules })`. Rules take
+    precedence over a tool's own `approval_required` / `auto_approvable`
+    declarations: `:deny` blocks, `:allow` proceeds without the queue,
+    `:ask` queues regardless of auto-approvable.
+  - **Dangerous-rule guard**: an unrestricted `:allow` on a code-executing
+    tool (`bash`, `code`, `repl`, or `:all`) is downgraded to `:ask` unless
+    the ruleset is created with `auto_allow_dangerous: true` — "approve
+    once" can't become "approve anything". `dangerous_rules` reports which
+    rules were affected.
+
 ## [0.30.1] — 2026-08-06
 
 ### Fixed

data/lib/ask/agent/events.rb

@@ -34,6 +34,14 @@ module Ask
       # Emitted when a session was forked from a checkpoint.
       SessionForked = Data.define(:session_id, :forked_id, :seq)
 
+      # Emitted when the task list changed (todo_write tool); carries the
+      # full entry list for live rendering.
+      TodoUpdated = Data.define(:todos)
+      # Plan mode lifecycle.
+      PlanProposed = Data.define(:plan)
+      PlanApproved = Data.define(:plan)
+      PlanRejected = Data.define(:plan)
+
       LoopDetected = Data.define(:tool_name, :repeated_count)
       MaxTurnsExceeded = Data.define(:max_turns)
 

data/lib/ask/agent/exit_plan_mode.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "ask/tools/tool"
+require "ask/result"
+
+module Ask
+  module Agent
+    # Presents the model's plan for human approval at the end of plan mode.
+    #
+    # Called after research: submits the plan to the session's plan queue
+    # and returns a pending result — the agent hands back the interim reply
+    # and waits for a human decision. On approval, plan mode turns off and
+    # the agent executes the plan; on rejection, it stays in plan mode with
+    # the rejection feedback in the conversation.
+    #
+    # Injected into the session by `Session.new(plan_mode: true)`.
+    class ExitPlanMode < Ask::Tool
+      description "Submit your plan for human approval and leave plan mode. " \
+                   "Call this when your research is done and you are ready to execute."
+
+      param :plan, type: :string, desc: "The plan you propose to execute", required: true
+
+      # @param plan_queue [Ask::Agent::ApprovalQueue] queue carrying plan
+      #   approvals; the session wires approve/reject callbacks
+      # @param on_submit [Proc, nil] called with the plan text when the plan
+      #   is submitted (used to emit PlanProposed)
+      def initialize(plan_queue:, on_submit: nil)
+        @plan_queue = plan_queue
+        @on_submit = on_submit
+        super()
+      end
+
+      def execute(plan:)
+        tool_call_id = Thread.current[:ask_agent_tool_call_id]
+        @plan_queue.submit(
+          tool_call_id: tool_call_id,
+          tool_name: "exit_plan_mode",
+          args: { plan: plan.to_s },
+          auto_approvable: false,
+          message: "Plan submitted for approval"
+        )
+        @on_submit&.call(plan.to_s)
+        Ask::Result.pending("Plan submitted for approval — waiting for a human decision")
+      end
+    end
+  end
+end

data/lib/ask/agent/policies/approval_policy.rb

@@ -32,13 +32,18 @@ module Ask
         #   rule-based classification on top of the tool's own declaration.
         #   Strings match tool names exactly, Regexps match against the name,
         #   and :all requires approval for every tool call.
+        # @param rules [Ask::Agent::Policies::PermissionRules, nil] persisted
+        #   allow/ask/deny patterns. Rules classify first and take precedence
+        #   over tool declarations: :deny blocks, :allow proceeds without the
+        #   queue, :ask queues regardless of auto-approvable.
         # @param tools [Array<Object>, nil] the session's resolved tool
         #   instances, used to read class-level declarations
         #   (`approval_required`, `auto_approvable`). When nil, only the
         #   rule-based lists classify calls.
-        def initialize(queue:, require_approval: nil, tools: nil)
+        def initialize(queue:, require_approval: nil, rules: nil, tools: nil)
           @queue = queue
           @require_approval = require_approval
+          @rules = rules
           @tools = Array(tools)
         end
 
@@ -46,12 +51,27 @@ module Ask
         #
         # @param tool_call [Ask::Agent::ToolCallInfo]
         # @param _context [Hash]
-        # @return [Hash] {action: :proceed} to run, or
-        #   {action: :pending, action_id:, reason:} to queue for approval
+        # @return [Hash] {action: :proceed} to run, {action: :pending,
+        #   action_id:, reason:} to queue for approval, or {action: :block,
+        #   reason:} to refuse
         def before_tool_call(tool_call, _context)
+          case @rules&.classify(tool_call.name, tool_call.arguments)
+          when :deny
+            return { action: :block, reason: "Denied by permission rules: '#{tool_call.name}'" }
+          when :allow
+            return { action: :proceed }
+          when :ask
+            return queue_for_approval(tool_call, auto_approvable: false)
+          end
+
           return { action: :proceed } unless approval_required?(tool_call.name)
 
-          auto_approvable = tool_auto_approvable?(tool_call.name)
+          queue_for_approval(tool_call, auto_approvable: tool_auto_approvable?(tool_call.name))
+        end
+
+        private
+
+        def queue_for_approval(tool_call, auto_approvable:)
           action_id = @queue.submit(
             tool_call_id: tool_call.id,
             tool_name: tool_call.name,
@@ -63,8 +83,6 @@ module Ask
           { action: :pending, action_id: action_id, reason: "Tool '#{tool_call.name}' requires approval" }
         end
 
-        private
-
         def approval_required?(tool_name)
           return true if @require_approval == :all
 

data/lib/ask/agent/policies/permission_rules.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module Agent
+    module Policies
+      # Persisted, matchable allow/ask/deny patterns for tool calls.
+      #
+      # Rules classify a tool call before it executes or prompts:
+      #
+      #   rules = Ask::Agent::Policies::PermissionRules.new do |r|
+      #     r.allow :bash, /^git (pull|push|status)/
+      #     r.ask   :bash, /^rm -rf/
+      #     r.deny  :write, %r{/\.env(\.local)?$}
+      #     r.ask   :destroy, :all
+      #   end
+      #
+      #   session = Ask::Agent::Session.new(
+      #     model: "gpt-4o",
+      #     approval: { rules: rules }
+      #   )
+      #
+      # Classification is first-match-wins, in declaration order: :allow runs
+      # the tool, :ask queues it for human approval, :deny blocks it. Rules
+      # take precedence over a tool's own `approval_required` / `auto_approvable`
+      # declarations — they are explicit user intent.
+      #
+      # Dangerous-rule guard: an :allow rule for a code-executing tool (bash,
+      # code, repl) whose argument pattern is unrestricted would let the model
+      # run anything without asking. Such rules are downgraded to :ask unless
+      # the ruleset was created with `auto_allow_dangerous: true` — "approve
+      # once, remember the pattern" must not become "approve everything".
+      class PermissionRules
+        # A single rule: tool pattern + optional argument pattern + decision.
+        Rule = Data.define(:tool_pattern, :argument_pattern, :decision) do
+          def matches?(tool_name, arguments)
+            tool_matches?(tool_name) && argument_matches?(arguments)
+          end
+
+          def tool_matches?(tool_name)
+            case tool_pattern
+            when :all then true
+            when Regexp then tool_pattern.match?(tool_name.to_s)
+            else tool_pattern.to_s == tool_name.to_s
+            end
+          end
+
+          def argument_matches?(arguments)
+            return true if argument_pattern.nil?
+
+            text = arguments.is_a?(Hash) ? JSON.generate(arguments) : arguments.to_s
+            case argument_pattern
+            when Regexp then argument_pattern.match?(text)
+            else text.include?(argument_pattern.to_s)
+            end
+          end
+
+          def universal?
+            argument_pattern.nil?
+          end
+        end
+
+        # Tools that execute arbitrary code — an unrestricted :allow rule on
+        # any of these is dangerous.
+        DANGEROUS_TOOLS = %i[bash code repl].freeze
+
+        # @param auto_allow_dangerous [Boolean] keep unrestricted :allow
+        #   rules on code-executing tools (default false — they downgrade to
+        #   :ask)
+        def initialize(auto_allow_dangerous: false, &block)
+          @auto_allow_dangerous = auto_allow_dangerous
+          @rules = []
+          instance_eval(&block) if block
+        end
+
+        # DSL — declare rules in priority order (first match wins).
+        def allow(tool_pattern, argument_pattern = nil)
+          add(:allow, tool_pattern, argument_pattern)
+        end
+
+        def ask(tool_pattern, argument_pattern = nil)
+          add(:ask, tool_pattern, argument_pattern)
+        end
+
+        def deny(tool_pattern, argument_pattern = nil)
+          add(:deny, tool_pattern, argument_pattern)
+        end
+
+        # @return [Array<Rule>] declared rules, in order
+        def rules = @rules.dup
+
+        # Classify a tool call.
+        #
+        # @param tool_name [String]
+        # @param arguments [Hash, String, nil] tool arguments (hash or JSON)
+        # @return [Symbol, nil] :allow, :ask, :deny — or nil when no rule
+        #   matches
+        def classify(tool_name, arguments = nil)
+          rule = @rules.find { |r| r.matches?(tool_name, arguments) }
+          return nil unless rule
+
+          if rule.decision == :allow && dangerous?(rule) && !@auto_allow_dangerous
+            :ask
+          else
+            rule.decision
+          end
+        end
+
+        # @return [Array<Rule>] rules that would allow unrestricted execution
+        #   of a code-executing tool
+        def dangerous_rules
+          @rules.select { |r| dangerous?(r) }
+        end
+
+        private
+
+        def add(decision, tool_pattern, argument_pattern)
+          @rules << Rule.new(tool_pattern, argument_pattern, decision)
+        end
+
+        def dangerous?(rule)
+          return false unless rule.decision == :allow && rule.universal?
+
+          rule.tool_pattern == :all || DANGEROUS_TOOLS.any? { |t| rule.tool_matches?(t) }
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/session.rb

@@ -23,7 +23,8 @@ module Ask
                      reflector: nil, telemetry: true, meta_agent: nil,
                      agent_dir: nil, evaluator: nil, audit_log: nil,
                      skills_disclosure: true, approval: nil,
-                     tool_call_repair: nil, checkpoints: false, **chat_options)
+                     tool_call_repair: nil, checkpoints: false,
+                     todos: false, plan_mode: false, **chat_options)
         @id = id || SecureRandom.uuid
         @agent_dir = agent_dir
         @max_turns = max_turns
@@ -47,6 +48,25 @@ module Ask
 
         @telemetry = telemetry.is_a?(Telemetry) ? telemetry : Telemetry.new(enabled: !!telemetry)
 
+        # Task list (todo_write tool) — built before resolve_tools so the
+        # tool can be injected with a reference to it.
+        @todos_enabled = !!todos
+        @todo_list = TodoList.new if @todos_enabled
+        @todo_list&.subscribe { |entries| emit(Events::TodoUpdated.new(todos: entries)) }
+
+        # Plan mode — research phase gated to read-only tools until a human
+        # approves the model's plan (submitted via the exit_plan_mode tool).
+        @plan_mode = plan_mode.is_a?(Hash) ? true : !!plan_mode
+        @plan_mode_read_only_tools = if plan_mode.is_a?(Hash) && plan_mode[:read_only_tools]
+          Array(plan_mode[:read_only_tools]).map(&:to_s)
+        else
+          %w[read glob grep web_search]
+        end
+        @plan_queue = ApprovalQueue.new(
+          on_approve: ->(action) { approve_plan(action) },
+          on_reject: ->(action) { reject_plan(action) }
+        ) if @plan_mode
+
         @tools = resolve_tools(tools)
         @chat = build_chat(model, system_prompt, @tools, **chat_options)
         @loop = Loop.new(max_turns: max_turns)
@@ -57,6 +77,15 @@ module Ask
         @approval_queue = build_approval(approval)
         @tool_call_repair = tool_call_repair
 
+        # Plan gate runs before user hooks and the approval policy: in plan
+        # mode, non-read-only tools are blocked outright (never queued).
+        if @plan_mode
+          @hooks = Hooks.new(
+            before_tool: [method(:plan_mode_gate)] + Array(@hooks.instance_variable_get(:@before_tool)),
+            after_tool: @hooks.instance_variable_get(:@after_tool)
+          )
+        end
+
         @system_context = build_system_context(system_prompt)
         apply_system_context
 
@@ -102,6 +131,12 @@ module Ask
       #
       # @return [Ask::Agent::ApprovalQueue, nil]
       attr_reader :approval_queue
+      # @return [Ask::Agent::ApprovalQueue, nil] queue carrying plan
+      #   approvals (only when plan mode is enabled)
+      attr_reader :plan_queue
+      # @return [Ask::Agent::TodoList, nil] session task list (only when
+      #   todos are enabled)
+      attr_reader :todo_list
 
       def run(message, tools: nil, reset: true)
         raise "Session deleted" if @deleted
@@ -329,17 +364,20 @@ module Ask
           end,
           state: adapter,
           # Checkpointing is restored automatically when the session has
-          # checkpoints in the store.
-          checkpoints: !adapter.get("#{id}#{CheckpointStore::HEAD_KEY}").nil?
+          # checkpoints in the store; todos likewise when the snapshot has
+          # a task list.
+          checkpoints: !adapter.get("#{id}#{CheckpointStore::HEAD_KEY}").nil?,
+          todos: !data[:todos].nil?
         )
 
-	        data[:messages].each do |msg|
-	          session.chat.add_message(
-	            role: msg[:role].to_sym,
-	            content: msg[:content],
-	            tool_call_id: msg[:tool_call_id]
-	          )
-	        end
+        data[:messages].each do |msg|
+          session.chat.add_message(
+            role: msg[:role].to_sym,
+            content: msg[:content],
+            tool_call_id: msg[:tool_call_id]
+          )
+        end
+        session.instance_variable_get(:@todo_list)&.restore(data[:todos])
 	
 	        session.instance_variable_set(:@messages, session.chat.messages.dup)
 	        session
@@ -425,13 +463,59 @@ module Ask
           model: data[:metadata][:model],
           tools: @tools,
           state: @state,
-          checkpoints: true
+          checkpoints: true,
+          todos: @todos_enabled,
+          plan_mode: @plan_mode
         )
         restore_into(forked, data)
         emit(Events::SessionForked.new(session_id: @id, forked_id: forked_id, seq: seq))
         forked
       end
 
+      # --- Plan mode ---
+
+      # @return [Boolean] whether the session is in plan mode (research
+      #   phase; non-read-only tools are blocked until the plan is approved)
+      def plan_mode? = @plan_mode
+
+      # Before-tool gate active while in plan mode: only read-only tools
+      # (and exit_plan_mode itself) run until a human approves the plan.
+      def plan_mode_gate(tool_call, _context)
+        return { action: :proceed } unless @plan_mode
+        return { action: :proceed } if @plan_mode_read_only_tools.include?(tool_call.name) || tool_call.name == "exit_plan_mode"
+
+        { action: :block, reason: "Plan mode: only read-only tools until the plan is approved" }
+      end
+
+      def approve_plan(action)
+        @plan_mode = false
+        plan = action.args[:plan] || action.args["plan"] || ""
+        emit(Events::PlanApproved.new(plan: plan))
+        complete_pending_tool(
+          tool_call_id: action.tool_call_id,
+          result: {
+            tool_name: "exit_plan_mode",
+            message: "Plan approved — execute it now.",
+            status: "success",
+            is_error: false
+          }
+        )
+      end
+
+      def reject_plan(action)
+        plan = action.args[:plan] || action.args["plan"] || ""
+        emit(Events::PlanRejected.new(plan: plan))
+        complete_pending_tool(
+          tool_call_id: action.tool_call_id,
+          result: {
+            tool_name: "exit_plan_mode",
+            message: "Plan rejected by the user — revise your plan and resubmit.",
+            status: "rejected",
+            is_error: false
+          }
+        )
+      end
+
       # --- Async (pending) tools ---
 
       # Registers a pending tool call (called by the loop when a tool
@@ -555,6 +639,7 @@ module Ask
         policy = Ask::Agent::Policies::ApprovalPolicy.new(
           queue: queue,
           require_approval: policy_opts[:require_approval],
+          rules: policy_opts[:rules],
           tools: @tools
         )
 
@@ -630,6 +715,15 @@ module Ask
         if skills_disclosure_enabled?
           resolved << Ask::Skills::LoadSkillTool.new(registry: @skills_registry) unless resolved.any? { |t| t.name == "load_skill" }
         end
+        if @todo_list
+          resolved << TodoWrite.new(todo_list: @todo_list) unless resolved.any? { |t| t.name == "todo_write" }
+        end
+        if @plan_mode
+          resolved << ExitPlanMode.new(
+            plan_queue: @plan_queue,
+            on_submit: ->(plan) { emit(Events::PlanProposed.new(plan: plan)) }
+          ) unless resolved.any? { |t| t.name == "exit_plan_mode" }
+        end
         resolved
       end
 
@@ -694,6 +788,7 @@ module Ask
         end
         target.instance_variable_set(:@messages, target.chat.messages.dup)
         target.instance_variable_set(:@turn_count, data.dig(:metadata, :turn_count) || 0)
+        target.instance_variable_get(:@todo_list)&.restore(data[:todos])
       end
 
       # User-supplied tools only. Framework-injected tools (the built-in
@@ -716,6 +811,7 @@ module Ask
               created_at: Time.now.iso8601
             }
           },
+          todos: @todo_list&.to_h,
           metadata: {
             model: @chat.model.respond_to?(:id) ? @chat.model.id : @chat.model,
             tools: persisted_tools.map { |t| t.class.name },

data/lib/ask/agent/todo_list.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    # Session-scoped task list maintained by the model through the
+    # {TodoWrite} tool.
+    #
+    # The list is the externalized plan: the model writes it once and checks
+    # it against each step, humans see progress live (via the TodoUpdated
+    # event), and checkpoints carry it across rollbacks and forks.
+    class TodoList
+      STATUSES = %w[pending in_progress completed blocked].freeze
+
+      Entry = Data.define(:id, :title, :status) do
+        def to_h = { id: id, title: title, status: status }
+      end
+
+      def initialize
+        @entries = []
+        @next_id = 1
+        @mutex = Mutex.new
+        @listeners = []
+      end
+
+      # @return [Array<Entry>] snapshot of the current entries
+      def all
+        @mutex.synchronize { @entries.dup }
+      end
+
+      # Register a listener called with the full entry list after every
+      # change (used to emit TodoUpdated events for live rendering).
+      #
+      # @return [self]
+      def subscribe(&block)
+        @listeners << block
+        self
+      end
+
+      # @param title [String]
+      # @param status [String] pending, in_progress, completed, or blocked
+      # @return [Entry]
+      # @raise [ArgumentError] on empty title or invalid status
+      def add(title, status: "pending")
+        raise ArgumentError, "title is required" if title.to_s.strip.empty?
+
+        entry = @mutex.synchronize do
+          e = Entry.new(id: "todo_#{@next_id}", title: title.to_s, status: validate_status(status || "pending"))
+          @next_id += 1
+          @entries << e
+          e
+        end
+        notify
+        entry
+      end
+
+      # @param id [String] entry id from {Entry#id}
+      # @param status [String, nil]
+      # @param title [String, nil]
+      # @return [Entry] the updated entry
+      # @raise [ArgumentError] on unknown id or invalid status
+      def update(id, status: nil, title: nil)
+        entry = @mutex.synchronize do
+          index = @entries.index { |e| e.id == id }
+          raise ArgumentError, "no todo with id #{id.inspect}" unless index
+
+          @entries[index] = Entry.new(
+            id: id,
+            title: title.nil? ? @entries[index].title : title.to_s,
+            status: status.nil? ? @entries[index].status : validate_status(status)
+          )
+          @entries[index]
+        end
+        notify
+        entry
+      end
+
+      # @return [void]
+      def clear
+        @mutex.synchronize { @entries.clear }
+        notify
+        nil
+      end
+
+      # @return [Hash] serialized form for persistence (checkpoints)
+      def to_h
+        { entries: all.map(&:to_h) }
+      end
+
+      # Rebuild from a serialized snapshot (rollback, fork, load). Fires no
+      # events.
+      #
+      # @param data [Hash, nil]
+      # @return [void]
+      def restore(data)
+        @mutex.synchronize do
+          raw = Array(data&.dig(:entries) || data&.dig("entries") || [])
+          @entries = raw.map do |e|
+            Entry.new(
+              id: (e[:id] || e["id"]).to_s,
+              title: (e[:title] || e["title"]).to_s,
+              status: (e[:status] || e["status"]).to_s
+            )
+          end
+          @next_id = @entries.size + 1
+        end
+        nil
+      end
+
+      # @return [String] human-readable list
+      def to_s
+        entries = all
+        return "(no todos)" if entries.empty?
+
+        entries.map { |e| "[#{e.status}] #{e.title} (#{e.id})" }.join("\n")
+      end
+
+      private
+
+      def validate_status(status)
+        s = status.to_s
+        raise ArgumentError, "invalid status #{s.inspect}; valid: #{STATUSES.join(', ')}" unless STATUSES.include?(s)
+
+        s
+      end
+
+      def notify
+        snapshot = all
+        @listeners.each { |listener| listener.call(snapshot) }
+      end
+    end
+  end
+end

data/lib/ask/agent/todo_write.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "ask/tools/tool"
+require "ask/result"
+
+module Ask
+  module Agent
+    # Tool that maintains the session's task list ({TodoList}). The model
+    # writes and updates todos as it works; every result returns the full
+    # list, so one call both mutates and shows state. A TodoUpdated event
+    # fires on every change for live rendering.
+    #
+    # Injected into the session by `Session.new(todos: true)`.
+    class TodoWrite < Ask::Tool
+      description "Maintain a task list for the current job. " \
+                   "Use it to plan multi-step work and update statuses as steps finish. " \
+                   "Actions: add (with title), update (with id and status or title), list, clear."
+
+      param :action, type: :string, desc: "add, update, list, or clear", required: true
+      param :title, type: :string, desc: "Task title (required for add)", required: false
+      param :id, type: :string, desc: "Task id (required for update)", required: false
+      param :status, type: :string, desc: "pending, in_progress, completed, or blocked", required: false
+
+      # @param todo_list [Ask::Agent::TodoList] the session's task list
+      def initialize(todo_list:)
+        @todo_list = todo_list
+        super()
+      end
+
+      def execute(action:, title: nil, id: nil, status: nil)
+        case action
+        when "add"
+          @todo_list.add(title, status: status)
+        when "update"
+          @todo_list.update(id, status: status, title: title)
+        when "list"
+          # no-op — the result carries the full list
+        when "clear"
+          @todo_list.clear
+        else
+          return Ask::Result.error(message: "Unknown action #{action.inspect}; valid: add, update, list, clear")
+        end
+
+        Ask::Result.ok(data: format_list)
+      rescue ArgumentError => e
+        Ask::Result.error(message: e.message)
+      end
+
+      private
+
+      def format_list
+        entries = @todo_list.all
+        return "(no todos)" if entries.empty?
+
+        entries.map { |e| "[#{e.status}] #{e.title} (#{e.id})" }.join("\n")
+      end
+    end
+  end
+end

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.30.1"
+    VERSION = "0.32.0"
   end
 end

data/lib/ask/agent.rb

@@ -35,10 +35,14 @@ module Ask
       autoload :RateLimiter, "ask/agent/policies/rate_limiter"
       autoload :AuditLog, "ask/agent/policies/audit_log"
       autoload :ApprovalPolicy, "ask/agent/policies/approval_policy"
+      autoload :PermissionRules, "ask/agent/policies/permission_rules"
     end
 
     autoload :ToolCallRepair, "ask/agent/tool_call_repair"
     autoload :CheckpointStore, "ask/agent/checkpoint_store"
+    autoload :TodoList, "ask/agent/todo_list"
+    autoload :TodoWrite, "ask/agent/todo_write"
+    autoload :ExitPlanMode, "ask/agent/exit_plan_mode"
 
     module Middleware
       autoload :Base, "ask/agent/middleware/base"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.30.1
+  version: 0.32.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -175,6 +175,7 @@ files:
 - lib/ask/agent/definition.rb
 - lib/ask/agent/evaluator.rb
 - lib/ask/agent/events.rb
+- lib/ask/agent/exit_plan_mode.rb
 - lib/ask/agent/hooks.rb
 - lib/ask/agent/loop.rb
 - lib/ask/agent/meta_agent.rb
@@ -189,6 +190,7 @@ files:
 - lib/ask/agent/policies/approval_policy.rb
 - lib/ask/agent/policies/audit_log.rb
 - lib/ask/agent/policies/audit_log/active_record_writer.rb
+- lib/ask/agent/policies/permission_rules.rb
 - lib/ask/agent/policies/permissions.rb
 - lib/ask/agent/policies/rate_limiter.rb
 - lib/ask/agent/reflector.rb
@@ -204,6 +206,8 @@ files:
 - lib/ask/agent/system_context.rb
 - lib/ask/agent/telemetry.rb
 - lib/ask/agent/test.rb
+- lib/ask/agent/todo_list.rb
+- lib/ask/agent/todo_write.rb
 - lib/ask/agent/tool_abort_controller.rb
 - lib/ask/agent/tool_call_repair.rb
 - lib/ask/agent/tool_executor.rb