ask-agent 0.40.30 → 0.42.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cbbcaccaadc0c18309984778974b4bcd63266acfd5329b855bfe8549ceed08b
-  data.tar.gz: e57d10ac194c5fcd6811842955527da4aa1a029a8c1855cb386851230e1335b7
+  metadata.gz: fa59129858a82b94badc3ec8e378457e2de2d0ffca3d5814797bc5e5ac0bb25d
+  data.tar.gz: cb266f3ff5e66ddc0227fd609d8ba99141190dd433ffe7ef5ab221a620cbcda8
 SHA512:
-  metadata.gz: c82139550f7fceacc363517c898f904a63900ba886db8f41532818721892a7a4e6e7e06b8cba78757831bed9846849238a3561032ba9e868f98e370310d8b8b3
-  data.tar.gz: 0eb17641350c57e697802700645edb9cdd271c2313b90a625a97ddf756f1fc4ca3dde68643aa7c5336de3bcdbee445e712673fe8b9bac709bc8199ae819f47b7
+  metadata.gz: 2dfaaa16987bf0eee0c03d13b415b8b0b02a210291f264d4a550e1b4eb86ee84671af2c5ec3d6f5aed7cfa34eae82b17164ecc87a13e1f80ac90a54cc94ffad4
+  data.tar.gz: 6e0c7e726ec4bcc602b06efd47eb272d67ae5441a157b666561f74ae9b32834264ad950ef638a238b6afe3994657eb906c453069d34083c9f86ee7ea6a0cb04a

data/CHANGELOG.md

@@ -1,5 +1,58 @@
 ## [Unreleased]
 
+## [0.42.0] - 2026-09-23
+## [0.41.0] - 2026-09-23
+
+- Approval decisions can now be granted for the current project through a
+  host-provided `project_grants` collaborator; hosts own its persistence and
+  project identity. Ask App Server supplies a workspace-scoped implementation.
+
+### Added
+
+- Applying approval with `scope: :session` grants that tool for the session;
+  once/project approvals remain one-shot from Ask Agent's perspective. Grants
+  persist and restore with both `Session.load` and `SessionAdapter.resume`.
+- `approval: { mode: ... }` — the permission mode (`:full_access`,
+  `:ask_before_changes`, `:read_only`) is forwarded to
+  `Ask::Permissions::ApprovalPolicy` when `Session#build_approval` wires the
+  policy, so sessions can run under a baseline mode alongside
+  `require_approval:` / `rules:` / grants.
+
+### Fixed
+
+- **Approval / plan queue persistence restores without re-emitting and approves exactly once.**
+  `Session.persist!` stores JSON-safe queue snapshots (`approvals:`,
+  `plan_approvals:`); `Session.load` re-enables the queues only when the
+  blob carries pending actions and silently rebuilds pending-tool
+  registrations so a later approve/reject completes the original call once.
+  `SessionAdapter` snapshots carry the same state and resume restores it
+  without firing callbacks. Malformed snapshots (non-Hash, missing /
+  non-Array pendings, missing queue while pendings exist, non-empty target,
+  or `restore_pending` / `snapshot` failures) now raise a contextual
+  `Ask::Agent::Error` / `SessionAdapter::Error` instead of being silently
+  swallowed; nil snapshots and empty pending lists remain safe no-ops, and
+  queues predating the Permissions API persist as nil (documented
+  compatibility fallback that cannot strand actions). Framework-injected
+  tools (`load_skill`, `todo_write`, `exit_plan_mode`, memory tools,
+  `output_read`) are excluded from persisted tool lists, avoiding
+  `Session.load` reconstruction warnings.
+
+### Changed
+
+- **Plan-mode tool gate delegates to `Ask::Permissions::PlanModePolicy`.**
+  `Session` now configures one shared policy (`allowed_tools:` from the
+  session's read-only tool list, `exit_tool: "exit_plan_mode"`) instead of
+  hand-rolling the allow/block check in `plan_mode_gate`, which now only
+  checks that plan mode is still active and delegates. The gate hook is
+  still installed only when plan mode is enabled, and approval still turns
+  the gate off. Exposes the configured policy as `Session#plan_mode_policy`.
+- Unknown keys in the `approval:` hash now raise `ArgumentError` instead of
+  being silently dropped — a misspelled option previously disabled a safety
+  control with no signal. Accepted keys are unchanged: `queue:`,
+  `require_approval:`, `rules:`, `auto_approve:`, `session_grants:`,
+  `project_grants:`, and the new `mode:`.
+## [0.40.30] — 2026-09-23
+
 ### Added
 
 - **`Session#run(runtime_event_sink:)` forwards ask-runtime tool lifecycle events** through the agent loop and recursive turns to `ToolExecutor#execute_batch`.

data/README.md

@@ -120,6 +120,35 @@ under multiple OpenAI-compatible providers). A `provider:` passed to
 `Session.new` or declared in an agent `Definition` always wins over the global
 default.
 
+### Tool approval
+
+`Session.new(approval: ...)` turns on human-in-the-loop approval: matching
+tool calls queue on `session.approval_queue` instead of executing until
+`approve(id)` / `reject(id)` is called. `approval: true` enables defaults; a
+Hash accepts:
+
+| Option | Purpose |
+|---|---|
+| `require_approval:` | tool names / regexps / `:all` that must be approved |
+| `auto_approve:` | user-enabled rules keyed by tool name (pairs with `auto_approvable` tools) |
+| `rules:` | an `Ask::Permissions::PermissionRules` block (`allow` / `ask` / `deny`) |
+| `mode:` | baseline policy — `:full_access`, `:ask_before_changes`, or `:read_only` |
+| `queue:` | a custom `Ask::Permissions::ApprovalQueue` |
+| `session_grants:` / `project_grants:` | grant collaborators (session- and project-scoped approvals) |
+
+```ruby
+session = Ask::Agent::Session.new(
+  model: "gpt-4o",
+  tools: [SendEmail],
+  approval: { mode: :read_only }
+)
+```
+
+`mode:` is forwarded to `Ask::Permissions::ApprovalPolicy`: `:full_access`
+runs every tool without asking, `:ask_before_changes` queues tool calls for
+approval, and `:read_only` refuses them outright. Unknown keys in the
+`approval:` hash raise `ArgumentError` instead of being silently ignored.
+
 ## Durable sessions (ask-session)
 
 `Ask::Agent::SessionAdapter` bridges a session to an event-sourced

data/lib/ask/agent/session.rb

@@ -10,6 +10,12 @@ module Ask
       # loop registrations resurrecting ghost pending calls.
       RECENTLY_COMPLETED_MAX = 200
 
+      # Options accepted by the `approval:` hash. Unknown keys raise so a
+      # misspelled option can never silently disable a safety control.
+      APPROVAL_OPTIONS = %i[
+        queue require_approval rules auto_approve session_grants project_grants mode
+      ].freeze
+
       attr_reader :id, :chat, :tools, :turn_count, :created_at, :messages
       attr_reader :tool_calls_made, :total_input_tokens, :total_output_tokens, :total_cost
 
@@ -81,6 +87,7 @@ module Ask
                      reflector: nil, telemetry: true, meta_agent: nil,
                      agent_dir: nil, evaluator: nil, audit_log: nil,
                      skills_disclosure: true, approval: nil,
+                     session_grants: nil,
                      tool_call_repair: nil, checkpoints: false,
                      todos: false, plan_mode: false, memory: nil,
                      memory_learning: false, offload_large_outputs: false,
@@ -88,6 +95,10 @@ module Ask
                      **chat_options)
         @id = id || SecureRandom.uuid
         @agent_dir = agent_dir
+        @provided_session_grants = session_grants
+        @session_grants = nil
+        @project_grants = nil
+        @approval_policy = nil
         @max_turns = max_turns
         @max_tool_retries = max_tool_retries
         @parallel_tools = parallel_tools
@@ -201,7 +212,13 @@ module Ask
 
         # Plan gate runs before user hooks and the approval policy: in plan
         # mode, non-read-only tools are blocked outright (never queued).
+        # The allowed-tool decision lives in one shared PlanModePolicy;
+        # its #before_tool_call is hooked in only while plan mode is on.
         if @plan_mode
+          @plan_mode_policy = Ask::Permissions::PlanModePolicy.new(
+            allowed_tools: @plan_mode_read_only_tools,
+            exit_tool: "exit_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)
@@ -275,6 +292,10 @@ module Ask
       # @return [Ask::Permissions::ApprovalQueue, nil] queue carrying plan
       #   approvals (only when plan mode is enabled)
       attr_reader :plan_queue
+      # @return [Ask::Permissions::PlanModePolicy, nil] the shared policy
+      #   deciding which tools may run in plan mode (only when plan mode
+      #   is enabled)
+      attr_reader :plan_mode_policy
       # @return [Ask::Agent::TodoList, nil] session task list (only when
       #   todos are enabled)
       attr_reader :todo_list
@@ -287,6 +308,7 @@ module Ask
       # @return [Ask::Agent::ArtifactStore, nil] store for tool deliverables
       #   (only when the +artifacts:+ option is enabled)
       attr_reader :artifact_store
+      attr_reader :session_grants, :approval_policy
 
       def run(message, tools: nil, reset: true, attachments: nil, runtime_event_sink: nil)
         raise "Session deleted" if @deleted
@@ -512,6 +534,10 @@ module Ask
 
         data = deep_symbolize_keys(data)
 
+        approvals_snapshot = data[:approvals]
+        plan_snapshot = data[:plan_approvals]
+        grants_snapshot = data[:session_grants]
+
         session = new(
           id: data[:id],
           model: data.dig(:metadata, :model),
@@ -531,9 +557,14 @@ module Ask
           state: adapter,
           # Checkpointing is restored automatically when the session has
           # checkpoints in the store; todos likewise when the snapshot has
-          # a task list.
+          # a task list. Approval / plan queues are re-enabled only when the
+          # persisted blob carries pending actions — policy config (rules,
+          # require_approval lists) is not persisted, only queue state that
+          # the shared Permissions API supports.
           checkpoints: !adapter.get("#{id}#{CheckpointStore::HEAD_KEY}").nil?,
-          todos: !data[:todos].nil?
+          todos: !data[:todos].nil?,
+          approval: (approval_snapshot_pending?(approvals_snapshot) || grants_snapshot_present?(grants_snapshot)) ? true : nil,
+          plan_mode: approval_snapshot_pending?(plan_snapshot) ? true : false
         )
 
         data[:messages].each do |msg|
@@ -544,7 +575,8 @@ module Ask
           )
         end
         session.instance_variable_get(:@todo_list)&.restore(data[:todos])
-	
+        session.send(:restore_persisted_approvals, approvals_snapshot, plan_snapshot, grants_snapshot)
+
 	        session.instance_variable_set(:@messages, session.chat.messages.dup)
 	        session
       end
@@ -633,7 +665,8 @@ module Ask
           state: @state,
           checkpoints: true,
           todos: @todos_enabled,
-          plan_mode: @plan_mode
+          plan_mode: @plan_mode,
+          approval: (@approval_queue || self.class.grants_snapshot_present?(data[:session_grants])) ? true : nil
         )
         restore_into(forked, data)
         emit(Events::SessionForked.new(session_id: @id, forked_id: forked_id, seq: seq))
@@ -701,13 +734,13 @@ end
       #   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)
+      # Before-tool gate active while in plan mode: delegates the
+      # allowed-tool decision to the PlanModePolicy (read-only tools and
+      # exit_plan_mode itself) and proceeds once 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" }
+        @plan_mode_policy.before_tool_call(tool_call, context)
       end
 
       def approve_plan(action)
@@ -893,9 +926,19 @@ end
       #
       # `approval` accepts:
       #   - true            → queue with defaults
-      #   - a Hash          → { require_approval:, auto_approve: } for the policy
-      #   - an ApprovalQueue → uses it, with policy options from
-      #                        approval[:policy] if given
+      #   - a Hash          → { queue:, require_approval:, rules:,
+      #                         auto_approve:, session_grants:,
+      #                         project_grants:, mode: } — unknown keys
+      #                         raise; a nested `policy` option is not
+      #                         implemented
+      #   - an ApprovalQueue → uses it directly: policy options are not
+      #                        read from the queue, so everything runs
+      #                        with defaults except the queue's own
+      #                        existing callbacks, which are preserved
+      #
+      # `mode:` forwards to Ask::Permissions::ApprovalPolicy — one of
+      # :full_access, :ask_before_changes, :read_only (nil = declaration-
+      # driven defaults).
       #
       # When enabled, an ApprovalPolicy hook is prepended to the session's
       # before_tool hooks so approval-required tools queue instead of running.
@@ -904,6 +947,12 @@ end
 
         policy_opts = approval.is_a?(Hash) ? approval : {}
 
+        unknown = policy_opts.keys - APPROVAL_OPTIONS
+        unless unknown.empty?
+          label = unknown.size == 1 ? "option" : "options"
+          raise ArgumentError, "unknown approval #{label}: #{unknown.map(&:inspect).join(", ")}"
+        end
+
         queue = if approval.is_a?(Ask::Permissions::ApprovalQueue)
           approval
         elsif policy_opts[:queue].is_a?(Ask::Permissions::ApprovalQueue)
@@ -916,10 +965,23 @@ end
           )
         end
 
-        # Custom queues (subclasses, event-emitting wrappers) may come
-        # without callbacks — wire the session's defaults so approvals
-        # actually execute the tool call.
-        queue.on_approve ||= ->(action) { apply_approved_action(action) }
+        custom_grants = @provided_session_grants || policy_opts[:session_grants]
+        unless custom_grants.nil? || custom_grants.is_a?(Ask::Permissions::SessionPermissionGrants)
+          raise ArgumentError, "session_grants must be an Ask::Permissions::SessionPermissionGrants, got #{custom_grants.class}"
+        end
+        @session_grants = custom_grants || Ask::Permissions::SessionPermissionGrants.new
+        @project_grants = policy_opts[:project_grants]
+        if @project_grants && !(%i[grant granted?].all? { |method| @project_grants.respond_to?(method) })
+          raise ArgumentError, "project_grants must respond to grant and granted?"
+        end
+
+        # Preserve a custom queue callback, but grant session scope before it
+        # executes. If no callback is supplied, keep the default executor.
+        previous_approve = queue.on_approve
+        queue.on_approve = lambda do |action|
+          apply_approval_scope(action)
+          previous_approve ? previous_approve.call(action) : apply_approved_action(action)
+        end
         queue.on_reject ||= ->(action) { reject_pending_action(action) }
         # Register the pending tool call the moment the action is queued —
         # before the auto-approval drain — so completions always match even
@@ -938,8 +1000,12 @@ end
           queue: queue,
           require_approval: policy_opts[:require_approval],
           rules: policy_opts[:rules],
-          tools: @tools
+          tools: @tools,
+          session_grants: @session_grants,
+          project_grants: @project_grants,
+          mode: policy_opts[:mode]
         )
+        @approval_policy = policy
 
         # Prepend the approval gate so it runs before user hooks
         @hooks = Hooks.new(
@@ -989,6 +1055,17 @@ end
         end
       end
 
+      def apply_approval_scope(action)
+        return unless action.respond_to?(:resolution_scope) && action.tool_name
+
+        case action.resolution_scope
+        when :session
+          @session_grants&.grant(action.tool_name.to_s)
+        when :project
+          @project_grants&.grant(action.tool_name.to_s)
+        end
+      end
+
       # Notify the conversation that an action was rejected by the user.
       def reject_pending_action(action)
         complete_pending_tool(
@@ -1098,15 +1175,133 @@ 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])
+        # Approval + grant restore for checkpoint rollback/fork is silent,
+        # but malformed permission snapshots raise instead of being stranded.
+        target.send(:restore_persisted_approvals, data[:approvals], data[:plan_approvals], data[:session_grants])
       end
 
       # User-supplied tools only. Framework-injected tools (the built-in
-      # load_skill tool) are re-created by resolve_tools on every session, so
+      # load_skill tool, todo_write, exit_plan_mode, memory tools,
+      # output_read) are re-created by resolve_tools on every session, so
       # persisting them would leak framework internals into user data — and
-      # they cannot be auto-instantiated on load anyway (LoadSkillTool needs
-      # a registry).
+      # they cannot always be auto-instantiated on load anyway (LoadSkillTool
+      # needs a registry, ExitPlanMode needs a plan_queue).
       def persisted_tools
-        @tools.reject { |t| t.is_a?(Ask::Skills::LoadSkillTool) }
+        @tools.reject do |t|
+          t.is_a?(Ask::Skills::LoadSkillTool) ||
+            (defined?(TodoWrite) && t.is_a?(TodoWrite)) ||
+            (defined?(ExitPlanMode) && t.is_a?(ExitPlanMode)) ||
+            (defined?(MemoryWrite) && t.is_a?(MemoryWrite)) ||
+            (defined?(MemorySearch) && t.is_a?(MemorySearch)) ||
+            (defined?(OutputRead) && t.is_a?(OutputRead))
+        end
+      end
+
+      # JSON-safe v1 snapshot for a queue, or nil when there is no queue or
+      # it predates the shared Permissions API (compatibility fallback:
+      # nothing durable to persist, so nothing to restore — cannot strand
+      # pendings because an unsupported queue never contributed durable
+      # state). Raises Ask::Agent::Error with context when the queue
+      # supports the API but snapshotting fails.
+      def queue_snapshot_for(queue, queue_name = "approval")
+        return nil unless queue
+        return nil unless queue.respond_to?(:snapshot)
+
+        begin
+          queue.snapshot
+        rescue StandardError => e
+          raise Ask::Agent::Error, "Failed to snapshot #{queue_name} queue (#{queue.class}): #{e.class}: #{e.message}"
+        end
+      end
+
+      # Restore persisted queue snapshots into this session's queues without
+      # firing callbacks or emitting events. Pending-tool registrations are
+      # rebuilt silently so a later approve/reject still completes the
+      # original tool call exactly once.
+      #
+      # Compatibility fallback (cannot strand): a nil snapshot (approval off
+      # or unsupported queue) and an empty pending_actions list are safe
+      # no-ops. Any other state that would prevent a faithful restore —
+      # non-Hash snapshot, missing/non-Array pendings, missing queue or
+      # queue without restore support while pendings exist, a non-empty
+      # target queue, or a restore_pending failure — raises
+      # Ask::Agent::Error with queue context instead of silently dropping
+      # pending actions.
+      def restore_persisted_approvals(approvals_snapshot, plan_snapshot, grants_snapshot = nil)
+        restore_queue_snapshot(@approval_queue, approvals_snapshot, "approval")
+        restore_queue_snapshot(@plan_queue, plan_snapshot, "plan")
+        restore_grants_snapshot(@session_grants, grants_snapshot)
+        nil
+      end
+
+      def restore_grants_snapshot(grants, snapshot)
+        return if snapshot.nil?
+        raise Ask::Agent::Error, "Cannot restore session grants: snapshot must be a Hash" unless snapshot.is_a?(Hash)
+
+        tools = snapshot[:granted_tools] || snapshot["granted_tools"]
+        unless tools.is_a?(Array) && tools.all? { |tool| tool.is_a?(String) && !tool.empty? }
+          raise Ask::Agent::Error, "Cannot restore session grants: granted_tools must be an Array of non-empty Strings"
+        end
+        return if tools.empty?
+        raise Ask::Agent::Error, "Cannot restore session grants: session has no grants store" unless grants
+
+        begin
+          grants.restore_snapshot(snapshot)
+        rescue StandardError => e
+          raise Ask::Agent::Error, "Cannot restore session grants: #{e.class}: #{e.message}"
+        end
+      end
+
+      def restore_queue_snapshot(queue, snapshot, queue_name = "approval")
+        return nil if snapshot.nil?
+
+        unless snapshot.is_a?(Hash)
+          raise Ask::Agent::Error, "Cannot restore #{queue_name} queue: snapshot must be a Hash, got #{snapshot.class}"
+        end
+
+        pendings = snapshot[:pending_actions] || snapshot["pending_actions"]
+        if pendings.nil?
+          raise Ask::Agent::Error, "Cannot restore #{queue_name} queue: snapshot missing pending_actions"
+        end
+        unless pendings.is_a?(Array)
+          raise Ask::Agent::Error, "Cannot restore #{queue_name} queue: pending_actions must be an Array, got #{pendings.class}"
+        end
+        return nil if pendings.empty?
+
+        unless queue
+          raise Ask::Agent::Error, "Cannot restore #{queue_name} queue: session has no #{queue_name} queue but snapshot carries #{pendings.size} pending action(s)"
+        end
+        unless queue.respond_to?(:restore_pending) && queue.respond_to?(:pending_actions)
+          raise Ask::Agent::Error, "Cannot restore #{queue_name} queue: #{queue.class} does not support restore_pending"
+        end
+
+        # restore_pending requires an empty queue — a non-empty target means
+        # a second restore would duplicate or strand actions, so fail loudly
+        # instead of silently dropping either side.
+        if queue.respond_to?(:any_pending?) && queue.any_pending?
+          raise Ask::Agent::Error, "Cannot restore #{queue_name} queue: target queue already holds pending actions"
+        end
+
+        begin
+          queue.restore_pending(snapshot)
+        rescue StandardError => e
+          raise Ask::Agent::Error, "Cannot restore #{queue_name} queue: #{e.class}: #{e.message}"
+        end
+        queue.pending_actions.each do |action|
+          tool_call_id = action.tool_call_id
+          next unless tool_call_id
+
+          @pending_mutex.synchronize do
+            @pending_tools[tool_call_id] ||= {
+              tool_name: action.tool_name,
+              message: action.message || "Pending approval",
+              status: "pending",
+              tool_call_id: tool_call_id,
+              action_id: action.id
+            }
+          end
+        end
+        nil
       end
 
       # Persist content blocks as their +to_h+ hashes so attachments
@@ -1134,6 +1329,14 @@ end
             }
           },
           todos: @todo_list&.to_h,
+          # Durable permission state: JSON-safe v1 queue snapshots when the
+          # queue supports the shared Permissions API (#snapshot). Nil when
+          # approval is off or the queue predates the API (compatibility
+          # fallback — nothing durable to persist, so nothing to strand).
+          # Snapshot failures raise Ask::Agent::Error with queue context.
+          approvals: queue_snapshot_for(@approval_queue, "approval"),
+          plan_approvals: queue_snapshot_for(@plan_queue, "plan"),
+          session_grants: @session_grants&.snapshot,
           metadata: {
             model: @chat.model.respond_to?(:id) ? @chat.model.id : @chat.model,
             tools: persisted_tools.map { |t| t.class.name },
@@ -1245,6 +1448,22 @@ end
         end
       end
 
+      # True when a persisted approval snapshot carries at least one pending
+      # action. Used to decide whether Session.load should re-enable the
+      # approval / plan queue — policy config itself is never persisted.
+      def self.approval_snapshot_pending?(snapshot)
+        return false unless snapshot.is_a?(Hash)
+
+        pendings = snapshot[:pending_actions] || snapshot["pending_actions"]
+        pendings.is_a?(Array) && !pendings.empty?
+      end
+
+      def self.grants_snapshot_present?(snapshot)
+        return false unless snapshot.is_a?(Hash)
+        tools = snapshot[:granted_tools] || snapshot["granted_tools"]
+        tools.is_a?(Array) && !tools.empty?
+      end
+
       # Render the system context and apply it to the chat.
       def apply_system_context
         rendered = @system_context.render

data/lib/ask/agent/session_adapter.rb

@@ -94,6 +94,12 @@ module Ask
           )
         end
         agent.instance_variable_set(:@messages, agent.chat.messages.dup)
+        restore_persisted_approvals(
+          agent,
+          payload[:approvals] || payload["approvals"],
+          payload[:plan_approvals] || payload["plan_approvals"],
+          payload[:session_grants] || payload["session_grants"]
+        )
 
         new(agent: agent, host: host, session_id: session_id, create: false)
       end
@@ -238,10 +244,122 @@ module Ask
       def build_snapshot
         {
           messages: (@agent.messages || []).map(&:to_h),
-          turn_count: @agent.turn_count || 0
+          turn_count: @agent.turn_count || 0,
+          # Durable permission state: JSON-safe v1 queue snapshots when the
+          # agent exposes a queue supporting the shared Permissions API.
+          # Nil when approval is off or unsupported (compatibility fallback
+          # — nothing durable to persist, so nothing to strand). Snapshot
+          # failures raise SessionAdapter::Error with queue context.
+          approvals: self.class.queue_snapshot_for(@agent, :approval_queue),
+          plan_approvals: self.class.queue_snapshot_for(@agent, :plan_queue),
+          session_grants: self.class.grants_snapshot_for(@agent)
         }
       end
 
+      def self.queue_snapshot_for(agent, queue_name)
+        return nil unless agent.respond_to?(queue_name)
+
+        queue = agent.public_send(queue_name)
+        return nil unless queue
+        return nil unless queue.respond_to?(:snapshot)
+
+        begin
+          queue.snapshot
+        rescue StandardError => e
+          raise Error, "Failed to snapshot #{queue_name} queue (#{queue.class}): #{e.class}: #{e.message}"
+        end
+      end
+
+      def self.grants_snapshot_for(agent)
+        return nil unless agent.respond_to?(:session_grants)
+        grants = agent.public_send(:session_grants)
+        grants&.respond_to?(:snapshot) ? grants.snapshot : nil
+      rescue StandardError => e
+        raise Error, "Failed to snapshot session grants (#{grants.class}): #{e.class}: #{e.message}"
+      end
+
+      # Restore persisted queue snapshots into the agent without firing
+      # callbacks or emitting approval-required events. For real Sessions
+      # this delegates to the session's silent restore (which also rebuilds
+      # pending-tool registrations so approve/reject completes exactly
+      # once); for generic agents it restores directly when the surface
+      # allows.
+      #
+      # Compatibility fallback (cannot strand): nil snapshots and empty
+      # pending_actions lists are safe no-ops. Any other unrestorable state
+      # — non-Hash snapshot, missing/non-Array pendings, missing queue or
+      # queue without restore support while pendings exist, a non-empty
+      # target queue, or a restore_pending failure — raises
+      # SessionAdapter::Error (or Ask::Agent::Error from the session
+      # delegate) with queue context instead of silently dropping actions.
+      def self.restore_persisted_approvals(agent, approvals_snapshot, plan_snapshot, grants_snapshot = nil)
+        if agent.respond_to?(:restore_persisted_approvals, true)
+          agent.send(:restore_persisted_approvals, approvals_snapshot, plan_snapshot, grants_snapshot)
+          return
+        end
+
+        { approval_queue: approvals_snapshot, plan_queue: plan_snapshot }.each do |queue_name, snapshot|
+          restore_into_generic_queue(agent, queue_name, snapshot)
+        end
+        return if grants_snapshot.nil?
+
+        unless grants_snapshot.is_a?(Hash)
+          raise Error, "Cannot restore session grants: snapshot must be a Hash, got #{grants_snapshot.class}"
+        end
+        tools = grants_snapshot[:granted_tools] || grants_snapshot["granted_tools"]
+        unless tools.is_a?(Array) && tools.all? { |tool| tool.is_a?(String) && !tool.empty? }
+          raise Error, "Cannot restore session grants: granted_tools must be an Array of non-empty Strings"
+        end
+        return if tools.empty?
+        unless agent.respond_to?(:session_grants)
+          raise Error, "Cannot restore session grants: agent has no session grants surface"
+        end
+
+        grants = agent.public_send(:session_grants)
+        raise Error, "Cannot restore session grants: agent has no grants store" unless grants
+        begin
+          grants.restore_snapshot(grants_snapshot)
+        rescue StandardError => e
+          raise Error, "Cannot restore session grants: #{e.class}: #{e.message}"
+        end
+      end
+
+      def self.restore_into_generic_queue(agent, queue_name, snapshot)
+        return nil if snapshot.nil?
+
+        unless snapshot.is_a?(Hash)
+          raise Error, "Cannot restore #{queue_name} queue: snapshot must be a Hash, got #{snapshot.class}"
+        end
+
+        pendings = snapshot[:pending_actions] || snapshot["pending_actions"]
+        if pendings.nil?
+          raise Error, "Cannot restore #{queue_name} queue: snapshot missing pending_actions"
+        end
+        unless pendings.is_a?(Array)
+          raise Error, "Cannot restore #{queue_name} queue: pending_actions must be an Array, got #{pendings.class}"
+        end
+        return nil if pendings.empty?
+        return nil unless agent.respond_to?(queue_name)
+
+        queue = agent.public_send(queue_name)
+        unless queue
+          raise Error, "Cannot restore #{queue_name} queue: agent has no #{queue_name} queue but snapshot carries #{pendings.size} pending action(s)"
+        end
+        unless queue.respond_to?(:restore_pending) && queue.respond_to?(:pending_actions)
+          raise Error, "Cannot restore #{queue_name} queue: #{queue.class} does not support restore_pending"
+        end
+        if queue.respond_to?(:any_pending?) && queue.any_pending?
+          raise Error, "Cannot restore #{queue_name} queue: target queue already holds pending actions"
+        end
+
+        begin
+          queue.restore_pending(snapshot)
+        rescue StandardError => e
+          raise Error, "Cannot restore #{queue_name} queue: #{e.class}: #{e.message}"
+        end
+        nil
+      end
+
       def self.deserialize_content(content)
         content.is_a?(Array) ? content.map { |block| Ask::Content.from_h(block) } : content
       end

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.40.30"
+    VERSION = "0.42.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.40.30
+  version: 0.42.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -141,14 +141,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement