ask-agent 0.40.29 → 0.41.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b55a3e7db1b87fa2e915014f6e8a787b24fe60df99602b14b95da3bb06fdf3a5
-  data.tar.gz: 57017799b4dfb6ab2f842212ba9eed1321bcd61c3872b92a5347a85e98f5ace7
+  metadata.gz: 511a1d165664c94fd0a9cc596e880d6f1d2cf43a3e1342d6954a221aed9c28ab
+  data.tar.gz: 3e253551f404881c1aea04517c7fd5b15733e845751b113c51dcd3baf73f041e
 SHA512:
-  metadata.gz: ef7705c41d359caed21b9424f09ec1aaf6164b3f0d773b78fdbfe0173a7f56dc1bff0af819d6aedb237fb45bdf990246282c2bfa4e1a64864df2d639f6c6d8e3
-  data.tar.gz: '08aed23b7e951f35182a683d52ae2c67d534fb2ccf97d2c1a6fc99ec505e49ce88be55225b9250eae6a1fb8d18e6aaaeb17994cb0ddf11b207a9a34fa14231c9'
+  metadata.gz: 1cc67751a3b745ebd674be1351f071d440746be4f985a3a82a3d36514473bb7249e1ba2a7a91692adf5fc557aedec88b106e67ceb1555fd36cec9ab24a2962f0
+  data.tar.gz: d6bb8e963ee254d668826cf713e35484634e7ab98900b850d15e7a3bf246bc859e1c4761802bb2c85b312fe2486e085007711e21dab3240252c67ebc337580d4

data/CHANGELOG.md

@@ -1,9 +1,75 @@
 ## [Unreleased]
 
+## [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`.
 
+### Changed
+
+- **Permission machinery extracted to the `ask-permissions` gem.**
+  `Ask::Agent::ApprovalQueue`, `Ask::Agent::Policies::ApprovalPolicy`,
+  `Ask::Agent::Policies::PermissionRules`, and
+  `Ask::Agent::Policies::Permissions` are removed from ask-agent; the same
+  classes now ship as `Ask::Permissions::ApprovalQueue`,
+  `Ask::Permissions::ApprovalPolicy`, `Ask::Permissions::PermissionRules`,
+  and `Ask::Permissions::Permissions` behind `require "ask/permissions"`.
+  Session keeps its agent-specific wiring — the `approval:` option still
+  builds the queue, wires on_approve/on_reject/on_submit callbacks, and
+  prepends the policy hook; the plan queue is unchanged apart from the
+  constant. Requires the new runtime dependency `ask-permissions >= 0.1.0`.
+
 ### Fixed
 
 - **`SessionAdapter.resume` surfaces every ask-session miss as

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/exit_plan_mode.rb

@@ -20,7 +20,7 @@ module Ask
 
       param :plan, type: :string, desc: "The plan you propose to execute", required: true
 
-      # @param plan_queue [Ask::Agent::ApprovalQueue] queue carrying plan
+      # @param plan_queue [Ask::Permissions::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)

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
@@ -166,7 +177,7 @@ module Ask
         else
           %w[read glob grep web_search]
         end
-        @plan_queue = ApprovalQueue.new(
+        @plan_queue = Ask::Permissions::ApprovalQueue.new(
           on_approve: ->(action) { approve_plan(action) },
           on_reject: ->(action) { reject_plan(action) },
           # Same race closure as the tool approval queue: register the
@@ -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)
@@ -270,11 +287,15 @@ module Ask
       # created without approval support. Use it to inspect pending actions
       # and approve/reject them.
       #
-      # @return [Ask::Agent::ApprovalQueue, nil]
+      # @return [Ask::Permissions::ApprovalQueue, nil]
       attr_reader :approval_queue
-      # @return [Ask::Agent::ApprovalQueue, nil] queue carrying plan
+      # @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,22 +947,41 @@ end
 
         policy_opts = approval.is_a?(Hash) ? approval : {}
 
-        queue = if approval.is_a?(Ask::Agent::ApprovalQueue)
+        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::Agent::ApprovalQueue)
+        elsif policy_opts[:queue].is_a?(Ask::Permissions::ApprovalQueue)
           policy_opts[:queue]
         else
-          Ask::Agent::ApprovalQueue.new(
+          Ask::Permissions::ApprovalQueue.new(
             auto_approve: policy_opts[:auto_approve],
             on_approve: ->(action) { apply_approved_action(action) },
             on_reject: ->(action) { reject_pending_action(action) }
           )
         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
@@ -934,12 +996,16 @@ end
           })
         }
 
-        policy = Ask::Agent::Policies::ApprovalPolicy.new(
+        policy = Ask::Permissions::ApprovalPolicy.new(
           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