ask-permissions 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '073941c27cb5785b8101b3fac162f47382cec0de2034b47f63edcd757c2b032f'
-  data.tar.gz: 5675a346d09b4a52eabaa85b2795bc5dc5651d3e34afce230cff0745d723e598
+  metadata.gz: c087f59df91e1c192c30e0e6740ad8fe8d514da85d2e1c14fe29f21df1bfeb0b
+  data.tar.gz: 6463c8e2123aa2b2035905a9fd8ef1df602f3ad9bdbe7f04afb6d8dd8e7acb63
 SHA512:
-  metadata.gz: ea269312c2aa211ccb2b51a1133ce74f7ecb2f9d6bdab68440abc62289c3d6aebeab496c2e15ce330c9642de816c7b8098db565de4bfd6974790836c04de26b8
-  data.tar.gz: 050ad80d943e96accd166946da442b8705792cb1c25d291eae3b4988b5ec5f2faa047823566a311a98928a927e2a6f2997668612a8502faa3e653fd99ba81c77
+  metadata.gz: e4c4934516b4f0bb5d38c68eb23f0edcd2037f674aa20b3ad0df41ad3c0a52b197d9fd7543d47bbc89f45bf3455e7a551c0e2fbdb13f6b713a669363b2ec345a
+  data.tar.gz: 74c0911e5a65433aef1cd957262ea5d9074f8ff81cbd7bb017b1d6f76fd67cd2012ce3b6d2024a453752ed771fd9504b3441da7b2fefb1a468caffa25599b0d0

data/CHANGELOG.md

@@ -5,7 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.0] - Unreleased
+## [Unreleased]
+
+## [0.3.0] - 2026-09-23
+
+### Added
+
+- Add `PermissionRuleSet` for composing default and project rules with
+  deny-first precedence, plus versioned JSON-safe snapshots for portable
+  host-owned rule storage.
+- Allow `ApprovalPolicy` to receive optional `project_rules:` while
+  preserving the existing `rules:` API.
+## [0.2.0] - 2026-09-23
+
+### Added
+
+- Add a reusable plan-mode gate and make tool-declared human approval requirements override ordinary allow rules.
+- Add JSON-safe pending approval snapshots for hosts that resume sessions after a restart.
+- Add capability-aware approval modes for read-only, ask-before-changes, and full-access sessions.
+- Add approval resolution scopes (`once`/`session`/`project`) on explicit approvals and rejection feedback, carried on the resolved `Action` for the host to apply. Auto-approvals report `once`; snapshots stay pending-only.
+- Add thread-safe `SessionPermissionGrants` for whole-tool session-scoped grants with versioned JSON-safe snapshot/restore, wired into `ApprovalPolicy` via optional `session_grants:` without touching project rules.
+- Add optional host-owned `project_grants:` collaborator (`granted?(tool_name)`) to `ApprovalPolicy`; a matching session or project grant bypasses ordinary ask rules, `require_approval`/metadata, elevated-risk prompts, and `ask_before_changes` side-effect prompts, without bypassing explicit deny, `always_ask?`, or `read_only`. No project store is shipped.
+## [0.1.0] - 2026-09-23
 
 ### Added
 

data/README.md

@@ -12,6 +12,17 @@ Everything lives under the `Ask::Permissions` namespace:
 | `ApprovalPolicy` | Hook adapter: consults rules, `require_approval`, and tool metadata, then enqueues through a queue. |
 | `ApprovalQueue` | Stores pending `Action`s, auto-approves eligible work in order, fires one-argument callbacks. |
 | `Permissions` | Optional mode gate (`nil` by default, or `:ask_before_changes` / `:read_only` / `:full_access`) with sticky approvals per `tool_call_id`. |
+| `PlanModePolicy` | Allows only declared read-only tools and the plan-submission tool while plan mode is active. |
+| `SessionPermissionGrants` | Thread-safe whole-tool grants scoped to the current session, with versioned JSON-safe snapshot/restore for durable resume. |
+
+Tools that expose `always_ask?` cannot be approved by a matching ordinary
+`allow` rule; their calls enter the human approval queue and cannot be
+auto-approved.
+
+`ApprovalQueue#snapshot` and `#restore_pending` let a session host persist
+pending approvals alongside its durable session state. Restoring does not
+re-emit submission events or auto-approve work; the host remains responsible
+for replaying its event log and reconnecting the restored queue to its session.
 
 ## Installation
 
@@ -144,6 +155,31 @@ rules.allow "read_file", %r{/docs/}     # Regexp against the serialized args
 rules.allow "search"                    # any arguments
 ```
 
+### Project rule layers and snapshots
+
+Compose application defaults with host-selected project rules using
+`PermissionRuleSet`. A deny in either layer wins; otherwise a matching
+project decision overrides the default, and an unmatched project rule falls
+back to the default layer.
+
+```ruby
+defaults = Ask::Permissions::PermissionRules.new { deny :bash, /rm\s+-rf/ }
+project = Ask::Permissions::PermissionRules.new { allow :read_file }
+rules = Ask::Permissions::PermissionRuleSet.new(
+  default_rules: defaults,
+  project_rules: project
+)
+
+rules.classify(:bash, { command: "rm -rf /tmp" }) # => :deny
+rules.classify(:read_file)                        # => :allow
+```
+
+`PermissionRules#snapshot` and `PermissionRuleSet#snapshot` produce
+versioned, JSON-safe data restored with `.from_snapshot`. The gem does not
+persist rules or resolve project identity: the host must authorize and scope
+the storage itself. Pass a project's rules to `ApprovalPolicy` with
+`project_rules:` alongside default `rules:`.
+
 Introspection: `rules` and `dangerous_rules` (both in declaration order). Each entry is a `Rule` with `decision`, `declared_decision`, `effective_decision`, `tool_pattern`, `argument_pattern`, `dangerous`, plus the predicates `dangerous?` and `universal?` (unrestricted argument pattern — `argument_pattern` is `nil`, regardless of tool pattern) and the matchers `tool_matches?(name)`, `argument_matches?(args)`, and `matches?(name, args)`. `decision` and `declared_decision` always keep the decision as written at declaration time; `classify` returns `effective_decision`.
 
 ### Dangerous allow downgrade
@@ -190,10 +226,20 @@ policy = Ask::Permissions::ApprovalPolicy.new(
   queue: queue,                              # required
   rules: rules,                              # optional
   require_approval: ["bash", /^write_/],     # optional
-  tools: {"fetch" => fetch_tool}             # optional registry
+  tools: {"fetch" => fetch_tool},            # optional registry
+  session_grants: session_grants,            # optional SessionPermissionGrants
+  project_grants: project_grants             # optional host-owned collaborator responding to granted?(tool_name)
 )
 ```
 
+The optional `mode:` applies declared tool capabilities consistently: `:read_only`
+blocks side-effecting or undeclared-scope tools, `:ask_before_changes` queues
+them for a person, and `:full_access` bypasses ordinary risk gates. Explicit
+`ask`/`deny` rules still apply in every mode, and a tool's `always_ask?` remains
+non-bypassable. Tools with `:high` or `:critical` risk are queued unless an
+explicit allow rule or `:full_access` mode permits them; risk-gated approvals
+are never auto-approved.
+
 ### The hook: `before_tool_call`
 
 `before_tool_call(tool_call, context = nil)` expects `tool_call` to respond to `name`, `arguments`, and `id`. It returns exactly one of three shapes:
@@ -206,9 +252,15 @@ policy = Ask::Permissions::ApprovalPolicy.new(
 
 Resolution order — the first layer with an opinion wins:
 
-1. **`rules.classify(name, arguments)`** — `:deny` → block with the exact reason `"Denied by permission rules: '<name>'"`, `:allow` → proceed, `:ask` → enqueue with `auto_approvable: false`. An explicit `allow` rule therefore wins over `require_approval`.
-2. **`require_approval` / tool metadata** — if no rule matched, a `require_approval` pattern or a tool whose metadata reports `approval_required?` enqueues as `:pending`; `auto_approvable` comes from the tool's `auto_approvable?`.
-3. **Default** — otherwise the call proceeds. An unconfigured policy allows everything.
+1. **Explicit `deny` rule** — always blocks with the exact reason `"Denied by permission rules: '<name>'"`. Neither session nor project grants bypass it.
+2. **Tool `always_ask?`** — always enqueues with `auto_approvable: false` and cannot be bypassed by an `allow` rule, `:full_access`, or either grants collaborator.
+3. **`:read_only` mode** — blocks tools whose side-effect scope is not `:none`. Neither session nor project grants bypass it.
+4. **Explicit `allow` rule** — proceeds. An explicit `allow` therefore wins over `require_approval`.
+5. **Session or project grant** (`session_grants.granted?(name)` or `project_grants.granted?(name)`) — proceeds, bypassing ordinary `ask` rules, `require_approval` / `approval_required?` metadata, `:high`/`:critical` risk gates, and `:ask_before_changes` side-effect prompts.
+6. **Ordinary `ask` rule** — enqueues with `auto_approvable: false`.
+7. **`:full_access` mode** — proceeds (except `always_ask?` above).
+8. **`require_approval` / tool metadata / risk / `:ask_before_changes`** — enqueues as `:pending`; `auto_approvable` comes from the tool's `auto_approvable?` (risk and `:ask_before_changes` prompts never auto-approve).
+9. **Default** — otherwise the call proceeds. An unconfigured policy allows everything.
 
 `require_approval` accepts `nil`, `:all` (queue every tool), a `String`/`Symbol` (exact name), a `Regexp`, or an `Array` of those (any match).
 
@@ -232,7 +284,48 @@ queue.approve(action.id)                     # fires on_approve
 queue.reject(action.id)                      # fires on_reject
 ```
 
-Readers: `policy.queue`, `policy.rules`, `policy.require_approval`, `policy.tools`.
+Readers: `policy.queue`, `policy.rules`, `policy.require_approval`, `policy.tools`, `policy.session_grants`, `policy.project_grants`.
+
+### Session-scoped grants: `SessionPermissionGrants`
+
+Grants whole-tool access for the current session only. They are in-memory, per-instance (sharing one grants object shares grants; separate objects are isolated), and never rewrite project rules:
+
+```ruby
+grants = Ask::Permissions::SessionPermissionGrants.new
+grants.grant("bash")      # Symbol or String; duplicate grants are idempotent
+grants.granted?("bash")   # => true
+grants.revoke("bash")     # => self; unknown tools are a noop
+grants.granted_tools      # => ["bash"] (sorted Strings)
+grants.clear
+
+policy = Ask::Permissions::ApprovalPolicy.new(queue: queue, require_approval: "bash", session_grants: grants)
+policy.before_tool_call(tool_call, context)  # => {action: :proceed} while granted
+```
+
+Grants bypass ordinary `ask` rules, `require_approval` / `approval_required?`, high-risk prompts, and `:ask_before_changes` side-effect prompts. They never bypass an explicit `deny`, a tool's `always_ask?`, or `:read_only` mode.
+
+### Project-scoped grants: `project_grants`
+
+`ApprovalPolicy` also accepts an optional host-owned `project_grants:` collaborator. It only needs to respond to `granted?(tool_name)` — the host owns storage and persistence, so this gem ships no project store:
+
+```ruby
+policy = Ask::Permissions::ApprovalPolicy.new(
+  queue: queue,
+  require_approval: "bash",
+  session_grants: session_grants,   # optional, nil by default
+  project_grants: project_grants    # optional, nil by default
+)
+```
+
+A matching grant from **either** collaborator bypasses the same ordinary ask gates listed above; neither can bypass an explicit `deny`, `always_ask?`, or `:read_only`. When either (or both) is `nil`, existing behavior is preserved. `SessionPermissionGrants` stays isolated and session-owned — sharing one instance shares session grants, separate instances do not, and project grants never mutate session grants or project rules.
+
+For durable resume, persist `grants.snapshot` (`{version: 1, granted_tools: [...]}`) alongside session state and restore it later. Snapshots survive a JSON round-trip (symbol/string keys both accepted); invalid versions, non-Array payloads, or blank/non-String entries raise `ArgumentError`:
+
+```ruby
+snapshot = grants.snapshot
+restored = Ask::Permissions::SessionPermissionGrants.from_snapshot(JSON.parse(JSON.generate(snapshot)))
+restored.granted?("bash")  # => true
+```
 
 ### Auto-approval through the policy
 

data/VERSIONING.md

@@ -7,6 +7,7 @@ This repository follows the ask-rb (Ask gem) versioning convention: exact sequen
 - Every release advances the version by **exactly one step**. Never skip a number.
 - While pre-1.0 (`0.x`), an incompatible feature (API or behavior change) increments the **minor** digit by one: `0.1.0 -> 0.2.0`.
 - Compatible fixes increment the **patch** digit by one: `0.1.0 -> 0.1.1`, `0.2.0 -> 0.2.1`.
+- Patch numbers are single digits (`0` through `9`). After patch `9`, advance the minor digit by one and reset the patch to `0` (for example, `0.1.9 -> 0.2.0`); never publish a patch above `9`.
 - Skipping is never allowed: `0.1.0 -> 0.3.0` or `0.1.0 -> 0.1.2` from a single release are both violations.
 - The version source of truth is `lib/ask/permissions/version.rb`; the gemspec reads it from there.
 
@@ -19,4 +20,4 @@ This repository follows the ask-rb (Ask gem) versioning convention: exact sequen
 
 - **All releases go through `gemchain`** from the ask-rb workspace. Never `rake release`, `gem push`, or any other manual publish.
 - A release requires a **clean working tree**, **passing tests** (`bundle exec rake test`), and **version agreement** — `lib/ask/permissions/version.rb`, the `CHANGELOG.md` heading, and the built gemspec version must all name the same version.
-- No release has been made yet: `0.1.0` stays `Unreleased` until `gemchain` publishes it.
+- `0.1.0` was published through `gemchain` on 2026-09-23.

data/lib/ask/permissions/approval_policy.rb

@@ -4,31 +4,55 @@ module Ask
   module Permissions
     # Hook adapter that consults rules, require_approval, and tool metadata, then enqueues through a queue.
     class ApprovalPolicy
-      attr_reader :queue, :require_approval, :rules, :tools
+      MODES = %i[full_access ask_before_changes read_only].freeze
+      SIDE_EFFECT_SCOPES = %i[none session workspace project system external unknown].freeze
+
+      attr_reader :queue, :require_approval, :rules, :tools, :mode, :session_grants, :project_grants,
+        :project_rules
+
+      def initialize(queue:, require_approval: nil, rules: nil, tools: nil, mode: nil, session_grants: nil,
+        project_grants: nil, project_rules: nil)
+        raise ArgumentError, "Unknown permission mode: #{mode.inspect}" if mode && !MODES.include?(mode.to_sym)
 
-      def initialize(queue:, require_approval: nil, rules: nil, tools: nil)
         @queue = queue
         @require_approval = require_approval
-        @rules = rules
         @tools = tools
+        @mode = mode&.to_sym
+        @session_grants = session_grants
+        @project_grants = project_grants
+        @project_rules = project_rules
+
+        @rules = if project_rules
+                   PermissionRuleSet.new(default_rules: rules, project_rules: project_rules)
+                 else
+                   rules
+                 end
       end
 
       def before_tool_call(tool_call, _context = nil)
         name = tool_call.name.to_s
         args = tool_call.arguments
 
-        case rules&.classify(name, args)
-        when :deny
-          return { action: :block, reason: "Denied by permission rules: '#{name}'" }
-        when :allow
-          return { action: :proceed }
-        when :ask
-          return enqueue(tool_call, auto_approvable: false)
+        rule_decision = rules&.classify(name, args)
+        return { action: :block, reason: "Denied by permission rules: '#{name}'" } if rule_decision == :deny
+
+        # A tool's explicit human-confirmation requirement is a hard safety
+        # boundary: an ordinary allow rule must not be able to bypass it.
+        return enqueue(tool_call, auto_approvable: false) if always_ask?(name)
+
+        if mode == :read_only && side_effect_scope(name) != :none
+          return { action: :block, reason: "Read-only mode blocks tools with side effects (#{name})" }
         end
 
-        return { action: :proceed } unless approval_required?(name)
+        return { action: :proceed } if rule_decision == :allow
 
-        enqueue(tool_call, auto_approvable: auto_approvable?(name))
+        # In-session and project whole-tool grants bypass ordinary ask rules,
+        # approval_required gates, high-risk gates, and ask_before_changes
+        # side-effect prompts. They never bypass deny, always_ask, or
+        # read_only above.
+        return { action: :proceed } if granted?(name)
+
+        fallback_decision(tool_call, name, rule_decision)
       end
 
       def lookup(action_id)
@@ -59,6 +83,53 @@ module Ask
         !!(tool && tool.respond_to?(:auto_approvable?) && tool.auto_approvable?)
       end
 
+      def always_ask?(name)
+        tool = find_tool(name)
+        !!(tool && tool.respond_to?(:always_ask?) && tool.always_ask?)
+      end
+
+      def session_granted?(name)
+        grants = session_grants
+        !!(grants && grants.respond_to?(:granted?) && grants.granted?(name))
+      end
+
+      def project_granted?(name)
+        grants = project_grants
+        !!(grants && grants.respond_to?(:granted?) && grants.granted?(name))
+      end
+
+      def granted?(name)
+        session_granted?(name) || project_granted?(name)
+      end
+
+      def fallback_decision(tool_call, name, rule_decision)
+        return enqueue(tool_call, auto_approvable: false) if rule_decision == :ask
+        return { action: :proceed } if mode == :full_access
+
+        if mode == :ask_before_changes && side_effect_scope(name) != :none
+          return enqueue(tool_call, auto_approvable: false)
+        end
+
+        return enqueue(tool_call, auto_approvable: false) if elevated_risk?(name)
+        return { action: :proceed } unless approval_required?(name)
+
+        enqueue(tool_call, auto_approvable: auto_approvable?(name))
+      end
+
+      def elevated_risk?(name)
+        tool = find_tool(name)
+        risk = tool.risk_level if tool&.respond_to?(:risk_level)
+        risk = risk.to_sym if risk.respond_to?(:to_sym)
+        %i[high critical].include?(risk)
+      end
+
+      def side_effect_scope(name)
+        tool = find_tool(name)
+        scope = tool.side_effect_scope if tool&.respond_to?(:side_effect_scope)
+        scope = scope.to_sym if scope.respond_to?(:to_sym)
+        SIDE_EFFECT_SCOPES.include?(scope) ? scope : :unknown
+      end
+
       def find_tool(name)
         case tools
         when nil then nil

data/lib/ask/permissions/approval_queue.rb

@@ -6,8 +6,11 @@ module Ask
   module Permissions
     # Stores pending approval actions, auto-approves eligible work in order, and fires one-argument callbacks.
     class ApprovalQueue
+      RESOLUTION_SCOPES = %i[once session project].freeze
+
       Action = Data.define(
-        :id, :tool_call_id, :tool_name, :args, :auto_approvable, :status, :submitted_at, :message
+        :id, :tool_call_id, :tool_name, :args, :auto_approvable, :status, :submitted_at, :message,
+        :resolution_scope, :feedback
       ) do
         def auto_approvable?
           !!auto_approvable
@@ -28,6 +31,11 @@ module Ask
         def rejected?
           status == :rejected
         end
+
+        # Alias for hosts that think in terms of approval scope.
+        def scope
+          resolution_scope
+        end
       end
 
       attr_reader :auto_approve
@@ -56,7 +64,9 @@ module Ask
             auto_approvable: auto_approvable ? true : false,
             status: :pending,
             submitted_at: @clock.call,
-            message: message
+            message: message,
+            resolution_scope: nil,
+            feedback: nil
           )
           @actions[created.id] = created
           created
@@ -73,6 +83,71 @@ module Ask
         @mutex.synchronize { @actions.values.select(&:pending?) }
       end
 
+      # A JSON-safe snapshot of pending approvals for a durable session store.
+      # Resolved actions are deliberately omitted so a restored approval can
+      # never execute twice after a restart.
+      def snapshot
+        @mutex.synchronize do
+          {
+            version: 1,
+            next_id: @next_id,
+            pending_actions: @actions.values.select(&:pending?).map do |action|
+              {
+                id: action.id,
+                tool_call_id: action.tool_call_id,
+                tool_name: action.tool_name,
+                args: action.args,
+                auto_approvable: action.auto_approvable?,
+                message: action.message
+              }
+            end
+          }
+        end
+      end
+
+      # Reconstitutes pending actions without emitting new submission events
+      # or draining auto-approvals. The host owns replaying its durable event
+      # log; this restores only the actionable queue state.
+      def restore_pending(snapshot)
+        version = snapshot_value(snapshot, :version)
+        raise ArgumentError, "Unsupported approval snapshot version: #{version.inspect}" unless version == 1
+
+        entries = snapshot_value(snapshot, :pending_actions)
+        raise ArgumentError, "Approval snapshot pending_actions must be an Array" unless entries.is_a?(Array)
+
+        restored = entries.map do |entry|
+          id = snapshot_value(entry, :id)
+          tool_name = snapshot_value(entry, :tool_name)
+          raise ArgumentError, "Approval snapshot action id must be a positive Integer" unless id.is_a?(Integer) && id.positive?
+          raise ArgumentError, "Approval snapshot tool_name must be a String" unless tool_name.is_a?(String)
+
+          Action.new(
+            id: id,
+            tool_call_id: snapshot_value(entry, :tool_call_id),
+            tool_name: tool_name,
+            args: snapshot_value(entry, :args) || {},
+            auto_approvable: snapshot_value(entry, :auto_approvable) == true,
+            status: :pending,
+            submitted_at: @clock.call,
+            message: snapshot_value(entry, :message),
+            resolution_scope: nil,
+            feedback: nil
+          )
+        end
+        ids = restored.map(&:id)
+        raise ArgumentError, "Approval snapshot contains duplicate action ids" unless ids.uniq == ids
+
+        @mutex.synchronize do
+          raise ArgumentError, "Cannot restore approvals into a non-empty queue" unless @actions.empty?
+
+          restored.each { |action| @actions[action.id] = action }
+          requested_next_id = snapshot_value(snapshot, :next_id)
+          @next_id = [requested_next_id.to_i, ids.max.to_i].max
+        end
+
+        restored.size
+      end
+
       def pending?(id)
         @mutex.synchronize { @actions[id]&.pending? || false }
       end
@@ -85,20 +160,21 @@ module Ask
         @mutex.synchronize { @actions[id] }
       end
 
-      def approve(*ids)
-        resolve_all(ids) { |action| apply(action) }
+      def approve(*ids, scope: :once)
+        validated = validate_resolution_scope!(scope)
+        resolve_all(ids) { |action| apply(action, scope: validated) }
       end
 
-      def reject(*ids)
-        resolve_all(ids) { |action| reject_action(action) }
+      def reject(*ids, feedback: nil)
+        resolve_all(ids) { |action| reject_action(action, feedback: feedback) }
       end
 
-      def approve_all
-        approve(*pending_actions.map(&:id))
+      def approve_all(scope: :once)
+        approve(*pending_actions.map(&:id), scope: scope)
       end
 
-      def reject_all
-        reject(*pending_actions.map(&:id))
+      def reject_all(feedback: nil)
+        reject(*pending_actions.map(&:id), feedback: feedback)
       end
 
       def drain
@@ -121,12 +197,19 @@ module Ask
 
       private
 
-      def apply(action)
-        resolve(action.id, @on_approve, :approved)
+      def snapshot_value(hash, key)
+        raise ArgumentError, "Approval snapshot values must be Hashes" unless hash.is_a?(Hash)
+
+        hash.key?(key) ? hash[key] : hash[key.to_s]
       end
 
-      def reject_action(action)
-        resolve(action.id, @on_reject, :rejected)
+      def apply(action, scope: :once)
+        validated = validate_resolution_scope!(scope)
+        resolve(action.id, @on_approve, :approved, resolution_scope: validated)
+      end
+
+      def reject_action(action, feedback: nil)
+        resolve(action.id, @on_reject, :rejected, feedback: feedback)
       end
 
       def resolve_all(ids)
@@ -144,7 +227,16 @@ module Ask
         end
       end
 
-      def resolve(id, callback, status)
+      def validate_resolution_scope!(scope)
+        normalized = scope.respond_to?(:to_sym) ? scope.to_sym : scope
+        unless RESOLUTION_SCOPES.include?(normalized)
+          raise ArgumentError, "Unknown resolution scope: #{scope.inspect}. Valid: #{RESOLUTION_SCOPES.join(', ')}"
+        end
+
+        normalized
+      end
+
+      def resolve(id, callback, status, resolution_scope: nil, feedback: nil)
         previous = nil
         applying = nil
 
@@ -152,7 +244,7 @@ module Ask
           previous = @actions[id]
           raise UnknownApprovalError, "unknown pending approval: #{id.inspect}" unless previous&.pending?
 
-          applying = previous.with(status: :applying)
+          applying = previous.with(status: :applying, resolution_scope: resolution_scope, feedback: feedback)
           @actions[id] = applying
         end
 

data/lib/ask/permissions/permission_rule_set.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Ask
+  module Permissions
+    # Composes default and project rule layers into a single classifier.
+    #
+    # Resolution: any matched :deny from either layer wins. Otherwise the
+    # project decision wins over the default. If neither layer matches,
+    # classify returns nil.
+    class PermissionRuleSet
+      SNAPSHOT_VERSION = 1
+
+      attr_reader :default_rules, :project_rules
+
+      def initialize(default_rules: nil, project_rules: nil)
+        validate_layer!(default_rules, 'default_rules')
+        validate_layer!(project_rules, 'project_rules')
+
+        @default_rules = default_rules
+        @project_rules = project_rules
+      end
+
+      def classify(tool_name, args = nil)
+        default_decision = @default_rules&.classify(tool_name, args)
+        project_decision = @project_rules&.classify(tool_name, args)
+
+        return :deny if default_decision == :deny || project_decision == :deny
+
+        project_decision || default_decision
+      end
+
+      def snapshot
+        {
+          version: SNAPSHOT_VERSION,
+          default_rules: snapshot_layer(@default_rules, 'default_rules'),
+          project_rules: snapshot_layer(@project_rules, 'project_rules')
+        }
+      end
+
+      def self.from_snapshot(snapshot)
+        raise ArgumentError, 'Snapshot must be a Hash' unless snapshot.is_a?(Hash)
+        validate_snapshot_keys!(snapshot, %i[version default_rules project_rules])
+
+        version = snapshot_value(snapshot, :version)
+        raise ArgumentError, "Unsupported snapshot version: #{version.inspect}" unless version == 1
+
+        default_raw = snapshot_value(snapshot, :default_rules)
+        project_raw = snapshot_value(snapshot, :project_rules)
+        validate_snapshot_layer!(default_raw, 'default_rules')
+        validate_snapshot_layer!(project_raw, 'project_rules')
+
+        default_rules = default_raw ? PermissionRules.from_snapshot(default_raw) : nil
+        project_rules = project_raw ? PermissionRules.from_snapshot(project_raw) : nil
+
+        new(default_rules: default_rules, project_rules: project_rules)
+      end
+
+      private
+
+      def self.snapshot_value(hash, key)
+        return hash[key] if hash.key?(key)
+        return hash[key.to_s] if hash.key?(key.to_s)
+
+        raise ArgumentError, "Snapshot is missing #{key}"
+      end
+
+      def self.validate_snapshot_keys!(hash, allowed)
+        keys = hash.keys.map(&:to_s)
+        unknown = keys - allowed.map(&:to_s)
+        raise ArgumentError, "Snapshot has unknown fields: #{unknown.join(', ')}" unless unknown.empty?
+      end
+
+      def self.validate_snapshot_layer!(value, name)
+        return if value.nil? || value.is_a?(Hash)
+
+        raise ArgumentError, "Snapshot #{name} must be a Hash or nil"
+      end
+
+      def snapshot_layer(layer, name)
+        return nil unless layer
+        unless layer.respond_to?(:snapshot)
+          raise ArgumentError, "#{name} must respond to :snapshot to be serialized"
+        end
+
+        snapshot = layer.snapshot
+        raise ArgumentError, "#{name} snapshot must be a Hash" unless snapshot.is_a?(Hash)
+
+        snapshot
+      end
+
+      def validate_layer!(layer, name)
+        return if layer.nil?
+
+        unless layer.respond_to?(:classify)
+          raise ArgumentError, "#{name} must respond to :classify"
+        end
+      end
+    end
+  end
+end

data/lib/ask/permissions/permission_rules.rb

@@ -7,6 +7,9 @@ module Ask
   module Permissions
     # Evaluates tool-invocation rules and returns allow/ask/deny decisions.
     class PermissionRules
+      SNAPSHOT_VERSION = 1
+      VALID_DECISIONS = %w[allow ask deny].freeze
+      VALID_PATTERN_TYPES = %w[string symbol regexp all].freeze
       DANGEROUS_TOOLS = %i[bash code repl].freeze
 
       Rule = Data.define(
@@ -74,6 +77,58 @@ module Ask
         @mutex.synchronize { @dangerous_rules.dup }
       end
 
+      def snapshot
+        entries = rules.map do |rule|
+          entry = {
+            decision: rule.declared_decision.to_s,
+            tool_pattern: serialize_pattern(rule.tool_pattern)
+          }
+          entry[:argument_pattern] = serialize_pattern(rule.argument_pattern) if rule.argument_pattern
+          entry
+        end
+
+        { version: SNAPSHOT_VERSION, auto_allow_dangerous: @auto_allow_dangerous, rules: entries }
+      end
+
+      def self.from_snapshot(snapshot)
+        raise ArgumentError, 'Snapshot must be a Hash' unless snapshot.is_a?(Hash)
+        validate_snapshot_keys!(snapshot, %i[version auto_allow_dangerous rules], 'snapshot')
+
+        version = snapshot_value(snapshot, :version)
+        raise ArgumentError, "Unsupported snapshot version: #{version.inspect}" unless version == 1
+
+        auto_allow = snapshot_value(snapshot, :auto_allow_dangerous)
+        unless [true, false].include?(auto_allow)
+          raise ArgumentError, 'Snapshot auto_allow_dangerous must be true or false'
+        end
+
+        raw_rules = snapshot_value(snapshot, :rules)
+        raise ArgumentError, 'Snapshot rules must be an Array' unless raw_rules.is_a?(Array)
+
+        instance = new(auto_allow_dangerous: !!auto_allow)
+        raw_rules.each do |entry|
+          raise ArgumentError, 'Snapshot rule entry must be a Hash' unless entry.is_a?(Hash)
+          validate_snapshot_keys!(entry, %i[decision tool_pattern argument_pattern], 'rule entry')
+
+          decision_str = snapshot_value(entry, :decision)
+          raise ArgumentError, 'Rule entry missing decision' if decision_str.nil?
+          unless decision_str.is_a?(String) && VALID_DECISIONS.include?(decision_str)
+            raise ArgumentError, "Invalid decision: #{decision_str.inspect}"
+          end
+
+          tool_pattern_raw = snapshot_value(entry, :tool_pattern)
+          raise ArgumentError, 'Rule entry missing tool_pattern' if tool_pattern_raw.nil?
+          tool_pattern = deserialize_pattern(tool_pattern_raw)
+
+          argument_pattern_raw = optional_snapshot_value(entry, :argument_pattern)
+          argument_pattern = deserialize_pattern(argument_pattern_raw) unless argument_pattern_raw.nil?
+
+          instance.send(:register, decision_str.to_sym, tool_pattern, argument_pattern)
+        end
+
+        instance
+      end
+
       def classify(tool_name, args = nil)
         rule = rules.find { |candidate| candidate.matches?(tool_name, args) }
         rule&.effective_decision
@@ -93,6 +148,26 @@ module Ask
 
       private
 
+      def self.snapshot_value(hash, key)
+        return hash[key] if hash.key?(key)
+        return hash[key.to_s] if hash.key?(key.to_s)
+
+        raise ArgumentError, "Snapshot is missing #{key}"
+      end
+
+      def self.optional_snapshot_value(hash, key)
+        return hash[key] if hash.key?(key)
+        return hash[key.to_s] if hash.key?(key.to_s)
+
+        nil
+      end
+
+      def self.validate_snapshot_keys!(hash, allowed, name)
+        keys = hash.keys.map(&:to_s)
+        unknown = keys - allowed.map(&:to_s)
+        raise ArgumentError, "Snapshot #{name} has unknown fields: #{unknown.join(', ')}" unless unknown.empty?
+      end
+
       def register(decision, tool_pattern, argument_pattern)
         dangerous = dangerous_allow?(decision, tool_pattern, argument_pattern)
         effective = dangerous && !@auto_allow_dangerous ? :ask : decision
@@ -124,6 +199,77 @@ module Ask
 
         DANGEROUS_TOOLS.include?(tool_pattern.to_s.to_sym)
       end
+
+      REGEXP_FLAG_MAP = {
+        'i' => Regexp::IGNORECASE,
+        'm' => Regexp::MULTILINE,
+        'x' => Regexp::EXTENDED
+      }.freeze
+
+      def serialize_pattern(pattern)
+        case pattern
+        when Regexp
+          supported_options = Regexp::IGNORECASE | Regexp::MULTILINE | Regexp::EXTENDED
+          if (pattern.options & ~supported_options).nonzero?
+            raise ArgumentError, "Unsupported regexp options: #{pattern.options}"
+          end
+
+          flags_str = +''
+          flags_str << 'i' if (pattern.options & Regexp::IGNORECASE).nonzero?
+          flags_str << 'm' if (pattern.options & Regexp::MULTILINE).nonzero?
+          flags_str << 'x' if (pattern.options & Regexp::EXTENDED).nonzero?
+          { type: 'regexp', source: pattern.source, flags: flags_str }
+        when Symbol
+          pattern == :all ? { type: 'all' } : { type: 'symbol', value: pattern.to_s }
+        when String
+          { type: 'string', value: pattern }
+        else
+          raise ArgumentError, "Unsupported permission pattern type: #{pattern.class}"
+        end
+      end
+
+      def self.deserialize_pattern(raw)
+        raise ArgumentError, 'Pattern must be a Hash' unless raw.is_a?(Hash)
+
+        type = snapshot_value(raw, :type)
+        raise ArgumentError, "Invalid pattern type: #{type.inspect}" unless type.is_a?(String) && VALID_PATTERN_TYPES.include?(type)
+
+        allowed_keys = case type
+        when 'string', 'symbol' then %i[type value]
+        when 'regexp' then %i[type source flags]
+        when 'all' then %i[type]
+        end
+        validate_snapshot_keys!(raw, allowed_keys, 'pattern')
+
+        case type
+        when 'string'
+          value = snapshot_value(raw, :value)
+          raise ArgumentError, 'String pattern value must be a String' unless value.is_a?(String)
+
+          value
+        when 'symbol'
+          value = snapshot_value(raw, :value)
+          raise ArgumentError, 'Symbol pattern value must be a String' unless value.is_a?(String)
+
+          value.to_sym
+        when 'regexp'
+          source = snapshot_value(raw, :source)
+          flags_str = snapshot_value(raw, :flags)
+          raise ArgumentError, 'Regexp source must be a String' unless source.is_a?(String)
+          unless flags_str.is_a?(String) && flags_str.chars.uniq == flags_str.chars && flags_str.chars.all? { |flag| REGEXP_FLAG_MAP.key?(flag) }
+            raise ArgumentError, "Invalid regexp flags: #{flags_str.inspect}"
+          end
+
+          flags = flags_str.chars.reduce(0) { |sum, ch| sum | REGEXP_FLAG_MAP.fetch(ch) }
+          Regexp.new(source, flags)
+        when 'all'
+          :all
+        end
+      rescue RegexpError, TypeError => error
+        raise ArgumentError, "Invalid regexp pattern: #{error.message}"
+      end
+
+      private_class_method :deserialize_pattern
     end
   end
 end

data/lib/ask/permissions/plan_mode_policy.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Ask
+  module Permissions
+    # Blocks non-read-only tool calls while a session is preparing a plan.
+    # Install this hook only while plan mode is active.
+    class PlanModePolicy
+      DEFAULT_EXIT_TOOL = 'exit_plan_mode'
+      DEFAULT_REASON = 'Plan mode: only read-only tools until the plan is approved'
+
+      def initialize(allowed_tools:, exit_tool: DEFAULT_EXIT_TOOL, reason: DEFAULT_REASON)
+        @allowed_tools = Array(allowed_tools).map(&:to_s).freeze
+        @exit_tool = exit_tool.to_s
+        @reason = reason
+      end
+
+      def before_tool_call(tool_call, _context = nil)
+        name = tool_call.name.to_s
+        return { action: :proceed } if name == @exit_tool || @allowed_tools.include?(name)
+
+        { action: :block, reason: @reason }
+      end
+    end
+  end
+end

data/lib/ask/permissions/session_permission_grants.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Ask
+  module Permissions
+    # In-memory whole-tool grants scoped to the current session.
+    #
+    # A grant bypasses ordinary ask rules, approval_required metadata,
+    # high-risk gates, and ask_before_changes side-effect prompts when
+    # consulted through ApprovalPolicy#before_tool_call via the optional
+    # session_grants: collaborator. Grants never override an explicit deny
+    # rule, a tool's always_ask? requirement, or read_only mode.
+    #
+    # Grants live in memory only, are isolated per instance (sharing an
+    # instance shares grants; separate instances do not), and never touch
+    # project rules. Use #snapshot / #restore_snapshot (or .from_snapshot)
+    # to persist grants alongside durable session state.
+    class SessionPermissionGrants
+      SNAPSHOT_VERSION = 1
+
+      def initialize(granted_tools: [])
+        @mutex = Mutex.new
+        @granted = Set.new
+        Array(granted_tools).each { |name| grant(name) }
+      end
+
+      def grant(tool_name)
+        normalized = normalize_tool_name!(tool_name)
+        @mutex.synchronize { @granted.add(normalized) }
+        self
+      end
+
+      def revoke(tool_name)
+        normalized = normalize_tool_name!(tool_name)
+        @mutex.synchronize { @granted.delete(normalized) }
+        self
+      end
+
+      def granted?(tool_name)
+        normalized = normalize_tool_name(tool_name)
+        return false if normalized.nil?
+
+        @mutex.synchronize { @granted.include?(normalized) }
+      end
+
+      def granted_tools
+        @mutex.synchronize { @granted.to_a.sort }
+      end
+
+      def size
+        @mutex.synchronize { @granted.size }
+      end
+
+      def empty?
+        @mutex.synchronize { @granted.empty? }
+      end
+
+      def clear
+        @mutex.synchronize { @granted.clear }
+        self
+      end
+
+      # JSON-safe snapshot for a durable session store.
+      def snapshot
+        @mutex.synchronize do
+          { version: SNAPSHOT_VERSION, granted_tools: @granted.to_a.sort }
+        end
+      end
+
+      # Replaces current grants with validated snapshot contents.
+      def restore_snapshot(snapshot)
+        tools = validated_snapshot_tools!(snapshot)
+        @mutex.synchronize do
+          @granted.clear
+          tools.each { |name| @granted.add(name) }
+        end
+        self
+      end
+
+      def self.from_snapshot(snapshot)
+        new.restore_snapshot(snapshot)
+      end
+
+      private
+
+      def normalize_tool_name(tool_name)
+        return nil if tool_name.nil?
+        return nil unless tool_name.is_a?(String) || tool_name.is_a?(Symbol)
+
+        normalized = tool_name.to_s
+        normalized.empty? ? nil : normalized
+      end
+
+      def normalize_tool_name!(tool_name)
+        normalized = normalize_tool_name(tool_name)
+        raise ArgumentError, 'Tool name must be a non-empty String or Symbol' if normalized.nil?
+
+        normalized
+      end
+
+      def snapshot_value(hash, key)
+        raise ArgumentError, 'Session grants snapshot must be a Hash' unless hash.is_a?(Hash)
+
+        hash.key?(key) ? hash[key] : hash[key.to_s]
+      end
+
+      def validated_snapshot_tools!(snapshot)
+        version = snapshot_value(snapshot, :version)
+        unless version == SNAPSHOT_VERSION
+          raise ArgumentError, "Unsupported session grants version: #{version.inspect}"
+        end
+
+        entries = snapshot_value(snapshot, :granted_tools)
+        raise ArgumentError, 'Session grants snapshot granted_tools must be an Array' unless entries.is_a?(Array)
+
+        entries.map do |entry|
+          normalized = normalize_tool_name(entry)
+          raise ArgumentError, 'Session grants snapshot tool names must be non-empty Strings' if normalized.nil?
+
+          normalized
+        end.uniq
+      end
+    end
+  end
+end

data/lib/ask/permissions/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Permissions
-    VERSION = '0.1.0'
+    VERSION = '0.3.0'
   end
 end

data/lib/ask/permissions.rb

@@ -4,6 +4,9 @@ require 'ask/permissions/version'
 require 'ask/permissions/errors'
 require 'ask/permissions/tool_pattern'
 require 'ask/permissions/permission_rules'
+require 'ask/permissions/permission_rule_set'
 require 'ask/permissions/approval_queue'
 require 'ask/permissions/permissions'
 require 'ask/permissions/approval_policy'
+require 'ask/permissions/plan_mode_policy'
+require 'ask/permissions/session_permission_grants'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-permissions
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -70,8 +70,11 @@ files:
 - lib/ask/permissions/approval_policy.rb
 - lib/ask/permissions/approval_queue.rb
 - lib/ask/permissions/errors.rb
+- lib/ask/permissions/permission_rule_set.rb
 - lib/ask/permissions/permission_rules.rb
 - lib/ask/permissions/permissions.rb
+- lib/ask/permissions/plan_mode_policy.rb
+- lib/ask/permissions/session_permission_grants.rb
 - lib/ask/permissions/tool_pattern.rb
 - lib/ask/permissions/version.rb
 homepage: https://github.com/ask-rb/ask-permissions