ask-permissions 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '073941c27cb5785b8101b3fac162f47382cec0de2034b47f63edcd757c2b032f'
-  data.tar.gz: 5675a346d09b4a52eabaa85b2795bc5dc5651d3e34afce230cff0745d723e598
+  metadata.gz: af1fd0c9368ebb102f0ca805b7303d781bf29e862ea19145fc4efcf24025cbe9
+  data.tar.gz: 4ce78f5aaf769b55fde844e1de746c319bcbc33001e7e9cb1f90a25e1c9a4850
 SHA512:
-  metadata.gz: ea269312c2aa211ccb2b51a1133ce74f7ecb2f9d6bdab68440abc62289c3d6aebeab496c2e15ce330c9642de816c7b8098db565de4bfd6974790836c04de26b8
-  data.tar.gz: 050ad80d943e96accd166946da442b8705792cb1c25d291eae3b4988b5ec5f2faa047823566a311a98928a927e2a6f2997668612a8502faa3e653fd99ba81c77
+  metadata.gz: ab3cd320947d7426dfececa4f73625df5d073fc751249521ac93e4104eaaa36d43512d30f6b9c92e25be60c9eafc26b7327f0bc9593ca2f80d614c7cba5efc44
+  data.tar.gz: 29e4857b244341160b6fd856c056c5fc3f098bbf350b9f07424c8ab8b3c90de3bac55c505c5b0e2d461d2a5efa22a73e9bc3c943a989807bb747771b3d8e1982

data/CHANGELOG.md

@@ -5,7 +5,19 @@ 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.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
 
@@ -190,10 +201,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 +227,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 +259,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,48 @@ 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
+
+      def initialize(queue:, require_approval: nil, rules: nil, tools: nil, mode: nil, session_grants: nil,
+        project_grants: 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
       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 +76,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/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.2.0'
   end
 end

data/lib/ask/permissions.rb

@@ -7,3 +7,5 @@ require 'ask/permissions/permission_rules'
 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.2.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -72,6 +72,8 @@ files:
 - lib/ask/permissions/errors.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