ask-permissions 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '073941c27cb5785b8101b3fac162f47382cec0de2034b47f63edcd757c2b032f'
+  data.tar.gz: 5675a346d09b4a52eabaa85b2795bc5dc5651d3e34afce230cff0745d723e598
+SHA512:
+  metadata.gz: ea269312c2aa211ccb2b51a1133ce74f7ecb2f9d6bdab68440abc62289c3d6aebeab496c2e15ce330c9642de816c7b8098db565de4bfd6974790836c04de26b8
+  data.tar.gz: 050ad80d943e96accd166946da442b8705792cb1c25d291eae3b4988b5ec5f2faa047823566a311a98928a927e2a6f2997668612a8502faa3e653fd99ba81c77

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+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
+
+### Added
+
+- Initial permission rules, mode policies, approval policy, and generic approval queue for ask-rb.

data/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing — ask-permissions
+
+## Setup
+
+```sh
+bundle install
+```
+
+Requires Ruby >= 3.2 (see `ask-permissions.gemspec`).
+
+### Local sibling path overrides
+
+When testing against an unreleased sibling Ask gem, temporarily point the dependency at a local checkout instead of the published version — e.g. add a `path:` override in the `Gemfile` (or an equivalent Bundler local override) targeting the sibling directory. Revert the override before opening a PR; never commit path-specific local overrides.
+
+## Tests
+
+```sh
+bundle exec rake test                       # full suite
+bundle exec rake test TEST=test/permissions_test.rb   # single file
+```
+
+## Style
+
+- Every Ruby file starts with `# frozen_string_literal: true`.
+- RuboCop is the single style authority (global Ask RuboCop config via `.rubocop.yml`); run `rubocop` (globally installed — it is deliberately not a Gemfile dependency) and keep it clean alongside the tests.
+
+## Pull requests
+
+- Keep PRs focused: one change, one purpose.
+- Update `CHANGELOG.md` under the current `[X.Y.Z] - Unreleased` section for anything user-visible.
+- Tests are required for behavior changes; the suite and RuboCop must pass.
+
+## Scope
+
+This gem is single-purpose: framework-independent permission rules, policies, and approval queues for ask-rb. Features that belong to other Ask gems (agent loops, LLM providers, transport, etc.) stay out — contribute those to the owning repository instead.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,316 @@
+# Ask::Permissions
+
+Shared permission rules and approval workflows for the [ask-rb](https://github.com/ask-rb) ecosystem.
+
+`ask-permissions` answers one question before a tool runs: may this call proceed? It is framework-independent — **your agent owns session execution** (running turns, invoking tools, pausing and resuming), while this gem owns the reusable classification, queueing, and approval logic you plug into a `before_tool_call` hook.
+
+Everything lives under the `Ask::Permissions` namespace:
+
+| Class | Role |
+| --- | --- |
+| `PermissionRules` | Ordered `allow` / `ask` / `deny` rules over tool names and arguments; `classify` returns the first match. |
+| `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`. |
+
+## Installation
+
+```ruby
+# Gemfile
+gem "ask-permissions"
+```
+
+```sh
+bundle install
+```
+
+```ruby
+require "ask-permissions"   # or require "ask/permissions"
+```
+
+Requires Ruby >= 3.2.
+
+## ApprovalQueue
+
+The queue is the source of truth for pending human decisions. Each submission becomes an immutable `Action` (a `Data` object) with a **sequential integer id** (`1`, `2`, `3`, …) assigned at submission time.
+
+```ruby
+queue = Ask::Permissions::ApprovalQueue.new(
+  auto_approve: {"fetch" => true},   # Hash keyed by tool name; entry must be exactly true
+  on_submit:    ->(action) { UI.enqueue(action) },          # one argument: the Action
+  on_approve:   ->(action) { Session.resume(action.tool_call_id) },
+  on_reject:    ->(action) { Session.deny(action.tool_call_id) }
+)
+
+id = queue.submit(
+  tool_call_id: "tc-1",
+  tool_name: "bash",
+  args: {"command" => "ls"},
+  auto_approvable: false,
+  message: "needs eyes"
+)                                    # => 1 (integer id)
+
+queue[id]                            # => the Action (or nil)
+queue.pending_actions                # => Actions with status :pending
+queue.pending?(id)                   # => true / false
+queue.any_pending?                   # => true / false
+```
+
+### Resolving
+
+```ruby
+queue.approve(id)          # => [action] — fires on_approve(action); does not drain
+queue.reject(id)           # => [action] — fires on_reject(action); does not drain
+queue.approve(1, 2, 3)     # accepts several ids; returns only the resolved Actions
+queue.approve_all          # approves every pending Action (empty array if none)
+queue.reject_all
+queue.drain                # re-runs the auto-approval pass explicitly
+```
+
+Unknown or already-resolved ids are ignored — they never raise. `approve` / `reject` return only the subset that was still pending (in id order), or `[]` when nothing qualified, and they do **not** drain afterward.
+
+### Action
+
+Fields: `id`, `tool_call_id`, `tool_name`, `args`, `auto_approvable`, `status`, `submitted_at`, `message`.
+Statuses: `:pending` → `:applying` (transient, inside the callback) → `:approved` or `:rejected`.
+Predicates: `pending?`, `applying?`, `approved?`, `rejected?`, `auto_approvable?`. Actions are frozen.
+
+### Callbacks
+
+All three callbacks take **exactly one argument — the `Action`**:
+
+- `on_submit(action)` — fires while the action is still `:pending`, before any auto-approval.
+- `on_approve(action)` / `on_reject(action)` — fire during resolution. If they raise, the action rolls back to `:pending` and the exception propagates.
+
+### Auto-approval
+
+Auto-approval needs **both** conditions:
+
+1. the submission carries `auto_approvable: true`, and
+2. `auto_approve` contains that tool name with the value exactly `true`.
+
+```ruby
+queue = Ask::Permissions::ApprovalQueue.new(auto_approve: {"read" => true})
+queue.submit(tool_call_id: "tc-1", tool_name: "read", auto_approvable: true)
+# => immediately :approved via on_approve
+
+queue.submit(tool_call_id: "tc-2", tool_name: "read")                  # stays :pending
+queue.submit(tool_call_id: "tc-3", tool_name: "other", auto_approvable: true)  # stays :pending
+```
+
+Drain is **ordered and never overtakes a manual item**: it approves from the head of the queue while that head is eligible and stops at the first manual entry. Auto-drain runs on every `submit`. `approve` / `reject` do **not** drain, so work behind a manual item waits until the next `submit` or an explicit `queue.drain`.
+
+Queues are mutex-guarded and safe to share across threads. Approval state lives in memory only.
+
+## PermissionRules
+
+Rules are evaluated in declaration order; the first match wins.
+
+```ruby
+rules = Ask::Permissions::PermissionRules.new    # auto_allow_dangerous: false (default)
+
+rules.allow "read_file"
+rules.ask   "bash", "rm -rf"
+rules.deny  "delete_user"
+
+rules.classify("bash", {"command" => "sudo rm -rf /tmp"})  # => :ask
+rules.classify("read_file")                               # => :allow
+rules.classify("delete_user")                             # => :deny
+rules.classify("unknown")                                 # => nil (no match)
+
+rules.allow?("read_file")    # => true
+rules.ask?("bash", {"command" => "rm -rf /"})
+rules.deny?("delete_user")
+```
+
+`allow` / `ask` / `deny` take `(tool_pattern, argument_pattern = nil)` and return `self`, so they chain. `PermissionRules.new` also accepts an optional block, which is `instance_eval`'d against the ruleset:
+
+```ruby
+rules = Ask::Permissions::PermissionRules.new do
+  allow "read_file"
+  deny  "delete_user"
+  ask   "bash", "rm -rf"
+end
+```
+
+### Patterns
+
+- **Tool pattern** — exact `String`/`Symbol` name, `Regexp`, or `:all` (matches every tool).
+- **Argument pattern** (optional) — `String` (substring of the serialized args) or `Regexp` (against the serialized form). Hash args are serialized with `JSON.generate`; anything else with `to_s`. Omit it to match any arguments.
+
+```ruby
+rules.ask   "bash", "rm -rf"            # substring of the serialized args
+rules.allow "read_file", %r{/docs/}     # Regexp against the serialized args
+rules.allow "search"                    # any arguments
+```
+
+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
+
+An unrestricted `allow` on a dangerous tool is downgraded to `:ask` **for classification only**, so a broad allow can never silently permit an execution tool:
+
+```ruby
+rules = Ask::Permissions::PermissionRules.new
+rules.allow "bash"            # declared :allow, effective :ask
+rule = rules.rules.first
+rule.decision                 # => :allow (declared decision is preserved)
+rule.declared_decision        # => :allow
+rule.effective_decision       # => :ask
+rules.classify("bash")        # => :ask
+```
+
+The dangerous set is the public frozen `DANGEROUS_TOOLS` constant, `%i[bash code repl]`. The `:all` pattern and any `Regexp` that matches one of those names also counts as dangerous — so `rules.allow :all` downgrades *every* tool to `:ask`. The downgrade only applies when the declared decision is `:allow` **and** no argument pattern was given:
+
+```ruby
+rules.allow "bash", "ls -la"   # restricted allow → stays :allow
+rules.deny  "bash"             # deny/ask are never downgraded
+```
+
+`PermissionRules.new(auto_allow_dangerous: true)` disables the guard. That is an explicit opt-out — leave it off unless you have a narrowly scoped reason.
+
+## ApprovalPolicy
+
+`ApprovalPolicy` requires a `queue:`; everything else is optional:
+
+```ruby
+rules = Ask::Permissions::PermissionRules.new
+rules.deny  "delete_user"
+rules.ask   "bash", "rm -rf"
+rules.allow "read_file"
+
+queue = Ask::Permissions::ApprovalQueue.new(
+  auto_approve: {"fetch" => true},
+  on_submit:    ->(action) { UI.enqueue(action) },
+  on_approve:   ->(action) { Session.resume(action.tool_call_id) },
+  on_reject:    ->(action) { Session.deny(action.tool_call_id) }
+)
+
+policy = Ask::Permissions::ApprovalPolicy.new(
+  queue: queue,                              # required
+  rules: rules,                              # optional
+  require_approval: ["bash", /^write_/],     # optional
+  tools: {"fetch" => fetch_tool}             # optional registry
+)
+```
+
+### 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:
+
+```ruby
+{action: :proceed}
+{action: :block, reason: "Denied by permission rules: 'delete_user'"}
+{action: :pending, action_id: 1, reason: "Tool 'bash' requires approval"}
+```
+
+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.
+
+`require_approval` accepts `nil`, `:all` (queue every tool), a `String`/`Symbol` (exact name), a `Regexp`, or an `Array` of those (any match).
+
+The `tools` registry may be a `Hash` (String or Symbol keys), an `Array` of objects that respond to `name`, or any object indexable with `[]`. Values should respond to `approval_required?` and/or `auto_approvable?`:
+
+```ruby
+tools = {"fetch" => fetch_tool}   # fetch_tool.approval_required? && fetch_tool.auto_approvable?
+```
+
+### Looking up and resolving
+
+`result[:action_id]` **is** the queue's action id — exactly what `queue.submit` returned (sequential integers assigned in submission order). `policy.lookup(id)` simply delegates to `queue[id]`:
+
+```ruby
+result = policy.before_tool_call(tool_call, context)
+return proceed if result[:action] == :proceed
+return refuse(result[:reason]) if result[:action] == :block
+
+action = policy.lookup(result[:action_id])   # the queue Action, or nil
+queue.approve(action.id)                     # fires on_approve
+queue.reject(action.id)                      # fires on_reject
+```
+
+Readers: `policy.queue`, `policy.rules`, `policy.require_approval`, `policy.tools`.
+
+### Auto-approval through the policy
+
+Only the `require_approval` / tool-metadata path can set `auto_approvable: true` — an `ask` rule always enqueues with `auto_approvable: false`. Even then the queue must also list the tool in its `auto_approve` hash. A `:pending` result can therefore come back with the action already `:approved`; check `action.status` (or `action.approved?`) before pausing.
+
+## Wiring it into an agent
+
+`ApprovalPolicy` sits in your agent's tool-call hook; this gem never executes tools itself:
+
+```ruby
+result = policy.before_tool_call(tool_call, context)
+
+case result[:action]
+when :proceed then proceed(result)
+when :block   then refuse(result[:reason])
+when :pending
+  action = policy.lookup(result[:action_id])
+  action.approved? ? proceed(result) : pause_until_decided(action)
+end
+```
+
+`proceed` / `refuse` / `pause_until_decided`, `Session`, and `UI` stand in for your own integration. A human (or an automated reviewer) later resolves the submission through the queue — `queue.approve(action.id)` or `queue.reject(action.id)`.
+
+Notes for hook authors:
+
+- Callbacks are the only side-effect seam; if one raises, the action stays `:pending` (or rolls back to `:pending`) and your hook sees the exception.
+- Approving does **not** rewrite the rules: the next identical call is classified from scratch and queues again if it still matches an `ask` rule. Approve per submission, not per tool.
+- `result[:action_id]` is the queue's own action id; `policy.lookup(action_id)` just delegates to `queue[action_id]`.
+
+## Mode gate: `Permissions`
+
+`Ask::Permissions::Permissions` is the simpler mode-based gate. It blocks a fixed set of change tools and records a sticky approval per `tool_call_id`.
+
+```ruby
+gate = Ask::Permissions::Permissions.new   # mode: nil (default)
+
+result = gate.before_tool_call(tool_call, {})
+# => {action: :block, reason: "bash requires approval"}
+
+gate.pending_approvals            # => pending Approval entries
+gate.approve("tc-1")              # => true
+
+gate.before_tool_call(tool_call, {})
+# => {action: :proceed}   (same tool_call id, already approved)
+```
+
+- **Modes** — omit `mode:` and `mode` stays `nil`; blocked tools default to the symbols `:write`, `:edit`, `:bash`, `:destroy`. With an explicit mode (`:ask_before_changes`, `:read_only`, or `:full_access`) the blocked set comes from the mode — `:ask_before_changes` and `:read_only` block those same four defaults, `:full_access` blocks nothing — and **`blocked_tools:` is ignored**. Without a mode, a custom `blocked_tools:` list **replaces** the default entirely (entries may be Strings or Symbols; they normalize to Symbols). An unknown mode (including a String) raises `ArgumentError` with the exact message `"Unknown access mode: <mode>. Valid: full_access, ask_before_changes, read_only"`. With an explicit mode the block reason reads `"bash requires approval (mode: ask_before_changes)"`; with `mode` omitted it is just `"bash requires approval"`.
+- **Public constants** — `Permissions::DEFAULT_TOOLS` is the frozen default set (`%i[write edit bash destroy]`) and `Permissions::ACCESS_MODES` maps each mode key to a frozen config hash with a `:blocked_tools` key (`full_access` → `[]`, the others → `DEFAULT_TOOLS`). The pre-existing `DEFAULT_BLOCKED_TOOLS` and `MODE_BLOCKED_TOOLS` remain available as aliases derived from them.
+- **Sticky approvals** — keyed by `tool_call_id`. The first blocked call records one pending `Approval`; repeated calls with the same `tool_call_id` reuse it. `approve(tool_call_id)` returns `true` for **any existing entry** — pending or already approved — and `false` only when the id is unknown; it never raises. Once approved, later calls with that id proceed. Approving one `tool_call_id` never unlocks another. There is no reject API: an entry you never approve keeps blocking.
+- **Approval reminder** — the first blocked request for a `tool_call_id` writes a reminder to stderr (`warn`, i.e. `$stderr`); repeated checks against the same still-pending entry stay silent, and an expired entry that gets recreated on the next call warns again.
+- **Timeout** — `Permissions.new(timeout: 60)` expires **both pending and approved** entries once `now - created_at` **exceeds** the timeout (`elapsed > timeout` — an entry exactly at the timeout has *not* expired yet), measured from the entry's **original** `created_at`. Expiry is acted on by `before_tool_call` for that `tool_call_id`: the stale entry is removed, a fresh pending `Approval` is recorded with a new `created_at`, and the call blocks again. `pending_approvals` only lists entries whose current status is `:pending` — it never purges expired ones. Without `timeout:` nothing ever expires.
+- Tool names normalize to **Symbols** (so `Approval#tool_name` is a Symbol like `:bash`); the gate is mutex-guarded.
+
+Prefer `ApprovalPolicy` for new integrations — it composes with ordered rules and the shared queue. Reach for the mode gate when you only need coarse "block changes until approved" behavior.
+
+## Defaults and safety caveats
+
+- **Unconfigured means allow.** `ApprovalPolicy.new(queue: queue)` with no rules, no `require_approval`, and no tool metadata proceeds on every call; a `PermissionRules` with no matching rule returns `nil`, which the policy treats as proceed. Configure before wiring a policy into an agent.
+- **Dangerous tools are downgraded, not blocked.** An unrestricted `allow` on `bash`/`code`/`repl` classifies as `:ask` (the rule's `decision` stays `:allow`; `effective_decision` is `:ask`), but `auto_allow_dangerous: true` turns the guard off — and `:full_access` in the mode gate blocks nothing (`blocked_tools:` is ignored whenever a mode is set).
+- **Auto-approve is opt-in twice.** The queue's `auto_approve` hash must contain the tool name `=> true` *and* the submission must be `auto_approvable`; `require_approval` items without matching tool metadata always wait for a human.
+- **Auto-approval never skips the line.** A manual item halts the drain until a human resolves it; later auto items do not jump ahead. `approve` / `reject` do not resume the drain themselves — the next `submit` or an explicit `queue.drain` does.
+- **Approval state is in memory.** Queues and gate approvals are not persisted and do not survive a restart.
+- **Queue approvals are per submission; gate approvals are sticky per `tool_call_id`.**
+- **Callback failures are visible.** `on_submit` / `on_approve` / `on_reject` exceptions propagate and leave actions `:pending`; keep callbacks idempotent.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+Requires Ruby >= 3.2 (see `ask-permissions.gemspec`).
+
+## Versioning
+
+See [VERSIONING.md](VERSIONING.md). Every release advances the version by exactly one step, and all releases go through `gemchain` — never publish this gem by hand.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/RELEASE.md

@@ -0,0 +1,23 @@
+# Releasing — ask-permissions
+
+[VERSIONING.md](VERSIONING.md) is the canonical versioning document (exact sequential steps, version agreement rules). Follow it; this file only covers the release procedure.
+
+## Preconditions
+
+All must hold before any release:
+
+- **Clean working tree** — no uncommitted changes.
+- **Passing tests** — `bundle exec rake test` (and global `rubocop`) are green.
+- **Up-to-date CHANGELOG** — the `[X.Y.Z] - Unreleased` heading in `CHANGELOG.md` names the version being released and matches `lib/ask/permissions/version.rb` (version agreement per VERSIONING.md).
+- **Runtime dependencies available** — any runtime dependency of this gem (and of its dependents in the ecosystem) is resolvable from RubyGems at the required versions.
+- **Build verification** — the gem builds cleanly (`gem build ask-permissions.gemspec`) and the built artifact reports the expected version.
+
+## Publishing: gemchain only
+
+**ALL Ask ecosystem publishing goes through `gemchain`. Never run `rake release`, `gem push`, or any other manual publish.**
+
+Order matters:
+
+1. **ask-permissions is new** — publish it first, before releasing any dependent gem, so dependents resolve it from RubyGems.
+2. Then run gemchain's **cascade checks and dry run** across the affected gems (verify version agreement, changelog state, and dependency ordering without publishing). Use `gemchain guard` for pre-release checks and `gemchain update` where a version bump is needed; consult gemchain itself for exact subcommand syntax.
+3. **Actual publish requires explicit authorization** — do not publish until authorization is given, even if all checks pass.

data/VERSIONING.md

@@ -0,0 +1,22 @@
+# Versioning — ask-permissions
+
+This repository follows the ask-rb (Ask gem) versioning convention: exact sequential steps, never skipped numbers.
+
+## Increment rules
+
+- 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`.
+- 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.
+
+## Changelog
+
+- `CHANGELOG.md` keeps a `[X.Y.Z] - Unreleased` section that is filled in as work lands and dated only when that version ships.
+- Before any release, the unreleased changelog heading and `lib/ask/permissions/version.rb` must name the same version (version agreement).
+
+## Releasing
+
+- **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.

data/lib/ask/permissions/approval_policy.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+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
+
+      def initialize(queue:, require_approval: nil, rules: nil, tools: nil)
+        @queue = queue
+        @require_approval = require_approval
+        @rules = rules
+        @tools = tools
+      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)
+        end
+
+        return { action: :proceed } unless approval_required?(name)
+
+        enqueue(tool_call, auto_approvable: auto_approvable?(name))
+      end
+
+      def lookup(action_id)
+        queue[action_id]
+      end
+
+      private
+
+      def approval_required?(name)
+        return true if matches_require_approval?(require_approval, name)
+
+        tool = find_tool(name)
+        !!(tool && tool.respond_to?(:approval_required?) && tool.approval_required?)
+      end
+
+      def matches_require_approval?(criterion, name)
+        case criterion
+        when nil then false
+        when :all then true
+        when Array then criterion.any? { |entry| matches_require_approval?(entry, name) }
+        when Regexp then criterion.match?(name)
+        else criterion.to_s == name
+        end
+      end
+
+      def auto_approvable?(name)
+        tool = find_tool(name)
+        !!(tool && tool.respond_to?(:auto_approvable?) && tool.auto_approvable?)
+      end
+
+      def find_tool(name)
+        case tools
+        when nil then nil
+        when Hash then tools[name] || tools[name.to_sym]
+        when Array then tools.find { |tool| tool.respond_to?(:name) && tool.name.to_s == name }
+        else tools.respond_to?(:[]) ? tools[name] : nil
+        end
+      end
+
+      def enqueue(tool_call, auto_approvable:)
+        name = tool_call.name.to_s
+        reason = "Tool '#{name}' requires approval"
+        message = "Calling \"#{name}\" requires approval"
+
+        action_id = queue.submit(
+          tool_name: name,
+          args: tool_call.arguments,
+          tool_call_id: tool_call.id,
+          auto_approvable: auto_approvable,
+          message: message
+        )
+
+        { action: :pending, action_id: action_id, reason: reason }
+      end
+    end
+  end
+end

data/lib/ask/permissions/approval_queue.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module Ask
+  module Permissions
+    # Stores pending approval actions, auto-approves eligible work in order, and fires one-argument callbacks.
+    class ApprovalQueue
+      Action = Data.define(
+        :id, :tool_call_id, :tool_name, :args, :auto_approvable, :status, :submitted_at, :message
+      ) do
+        def auto_approvable?
+          !!auto_approvable
+        end
+
+        def pending?
+          status == :pending
+        end
+
+        def applying?
+          status == :applying
+        end
+
+        def approved?
+          status == :approved
+        end
+
+        def rejected?
+          status == :rejected
+        end
+      end
+
+      attr_reader :auto_approve
+      attr_accessor :on_approve, :on_reject, :on_submit
+
+      def initialize(on_approve: nil, on_reject: nil, auto_approve: {}, on_submit: nil, clock: nil)
+        @on_approve = on_approve
+        @on_reject = on_reject
+        @auto_approve = auto_approve || {}
+        @on_submit = on_submit
+        @clock = clock || -> { Time.now }
+        @actions = {}
+        @next_id = 0
+        @mutex = Mutex.new
+        @draining = false
+      end
+
+      def submit(tool_call_id:, tool_name:, args: {}, auto_approvable: false, message: nil)
+        action = @mutex.synchronize do
+          @next_id += 1
+          created = Action.new(
+            id: @next_id,
+            tool_call_id: tool_call_id,
+            tool_name: tool_name.to_s,
+            args: args.nil? ? {} : args,
+            auto_approvable: auto_approvable ? true : false,
+            status: :pending,
+            submitted_at: @clock.call,
+            message: message
+          )
+          @actions[created.id] = created
+          created
+        end
+
+        @on_submit&.call(action)
+
+        drain
+
+        action.id
+      end
+
+      def pending_actions
+        @mutex.synchronize { @actions.values.select(&:pending?) }
+      end
+
+      def pending?(id)
+        @mutex.synchronize { @actions[id]&.pending? || false }
+      end
+
+      def any_pending?
+        @mutex.synchronize { @actions.each_value.any?(&:pending?) }
+      end
+
+      def [](id)
+        @mutex.synchronize { @actions[id] }
+      end
+
+      def approve(*ids)
+        resolve_all(ids) { |action| apply(action) }
+      end
+
+      def reject(*ids)
+        resolve_all(ids) { |action| reject_action(action) }
+      end
+
+      def approve_all
+        approve(*pending_actions.map(&:id))
+      end
+
+      def reject_all
+        reject(*pending_actions.map(&:id))
+      end
+
+      def drain
+        return self unless start_draining
+
+        begin
+          while (head = next_auto_head)
+            begin
+              apply(head)
+            rescue UnknownApprovalError
+              next
+            end
+          end
+        ensure
+          stop_draining
+        end
+
+        self
+      end
+
+      private
+
+      def apply(action)
+        resolve(action.id, @on_approve, :approved)
+      end
+
+      def reject_action(action)
+        resolve(action.id, @on_reject, :rejected)
+      end
+
+      def resolve_all(ids)
+        actions = @mutex.synchronize do
+          ids.flatten.uniq
+             .filter_map { |id| @actions[id] }
+             .select(&:pending?)
+             .sort_by(&:id)
+        end
+
+        actions.filter_map do |action|
+          yield action
+        rescue UnknownApprovalError
+          nil
+        end
+      end
+
+      def resolve(id, callback, status)
+        previous = nil
+        applying = nil
+
+        @mutex.synchronize do
+          previous = @actions[id]
+          raise UnknownApprovalError, "unknown pending approval: #{id.inspect}" unless previous&.pending?
+
+          applying = previous.with(status: :applying)
+          @actions[id] = applying
+        end
+
+        begin
+          callback&.call(applying)
+        rescue StandardError
+          @mutex.synchronize { @actions[id] = previous }
+          raise
+        end
+
+        resolved = applying.with(status: status)
+        @mutex.synchronize { @actions[id] = resolved }
+        resolved
+      end
+
+      def next_auto_head
+        @mutex.synchronize do
+          head = @actions.each_value.find(&:pending?)
+          head if head&.auto_approvable? && @auto_approve[head.tool_name] == true
+        end
+      end
+
+      def start_draining
+        @mutex.synchronize do
+          next false if @draining
+
+          @draining = true
+        end
+      end
+
+      def stop_draining
+        @mutex.synchronize { @draining = false }
+      end
+    end
+  end
+end

data/lib/ask/permissions/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Ask
+  module Permissions
+    class Error < StandardError
+    end
+
+    class UnknownApprovalError < Error
+    end
+  end
+end

data/lib/ask/permissions/permission_rules.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'tool_pattern'
+
+module Ask
+  module Permissions
+    # Evaluates tool-invocation rules and returns allow/ask/deny decisions.
+    class PermissionRules
+      DANGEROUS_TOOLS = %i[bash code repl].freeze
+
+      Rule = Data.define(
+        :decision, :declared_decision, :effective_decision, :tool_pattern, :argument_pattern, :dangerous
+      ) do
+        def dangerous?
+          dangerous
+        end
+
+        def universal?
+          argument_pattern.nil?
+        end
+
+        def tool_matches?(tool_name)
+          ToolPattern.match?(tool_pattern, tool_name)
+        end
+
+        def argument_matches?(args)
+          return true if argument_pattern.nil?
+
+          haystack = serialize(args)
+
+          case argument_pattern
+          when Regexp then argument_pattern.match?(haystack)
+          else haystack.include?(argument_pattern.to_s)
+          end
+        end
+
+        def matches?(tool_name, args = nil)
+          tool_matches?(tool_name) && argument_matches?(args)
+        end
+
+        private
+
+        def serialize(value)
+          value.is_a?(Hash) ? JSON.generate(value) : value.to_s
+        end
+      end
+
+      def initialize(auto_allow_dangerous: false, &block)
+        @auto_allow_dangerous = auto_allow_dangerous ? true : false
+        @rules = []
+        @dangerous_rules = []
+        @mutex = Mutex.new
+        instance_eval(&block) if block
+      end
+
+      def allow(tool_pattern, argument_pattern = nil)
+        register(:allow, tool_pattern, argument_pattern)
+      end
+
+      def ask(tool_pattern, argument_pattern = nil)
+        register(:ask, tool_pattern, argument_pattern)
+      end
+
+      def deny(tool_pattern, argument_pattern = nil)
+        register(:deny, tool_pattern, argument_pattern)
+      end
+
+      def rules
+        @mutex.synchronize { @rules.dup }
+      end
+
+      def dangerous_rules
+        @mutex.synchronize { @dangerous_rules.dup }
+      end
+
+      def classify(tool_name, args = nil)
+        rule = rules.find { |candidate| candidate.matches?(tool_name, args) }
+        rule&.effective_decision
+      end
+
+      def allow?(tool_name, args = nil)
+        classify(tool_name, args) == :allow
+      end
+
+      def ask?(tool_name, args = nil)
+        classify(tool_name, args) == :ask
+      end
+
+      def deny?(tool_name, args = nil)
+        classify(tool_name, args) == :deny
+      end
+
+      private
+
+      def register(decision, tool_pattern, argument_pattern)
+        dangerous = dangerous_allow?(decision, tool_pattern, argument_pattern)
+        effective = dangerous && !@auto_allow_dangerous ? :ask : decision
+
+        rule = Rule.new(
+          decision: decision,
+          declared_decision: decision,
+          effective_decision: effective,
+          tool_pattern: tool_pattern,
+          argument_pattern: argument_pattern,
+          dangerous: dangerous
+        )
+
+        @mutex.synchronize do
+          @rules << rule
+          @dangerous_rules << rule if dangerous
+        end
+
+        self
+      end
+
+      def dangerous_allow?(decision, tool_pattern, argument_pattern)
+        decision == :allow && argument_pattern.nil? && dangerous_tool?(tool_pattern)
+      end
+
+      def dangerous_tool?(tool_pattern)
+        return true if tool_pattern == :all
+        return DANGEROUS_TOOLS.any? { |name| tool_pattern.match?(name.to_s) } if tool_pattern.is_a?(Regexp)
+
+        DANGEROUS_TOOLS.include?(tool_pattern.to_s.to_sym)
+      end
+    end
+  end
+end

data/lib/ask/permissions/permissions.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Ask
+  module Permissions
+    # Mode gate that blocks change tools until approved, with sticky approvals per tool_call_id.
+    class Permissions
+      DEFAULT_TOOLS = %i[write edit bash destroy].freeze
+
+      ACCESS_MODES = {
+        full_access: { blocked_tools: [].freeze }.freeze,
+        ask_before_changes: { blocked_tools: DEFAULT_TOOLS }.freeze,
+        read_only: { blocked_tools: DEFAULT_TOOLS }.freeze
+      }.freeze
+
+      DEFAULT_BLOCKED_TOOLS = DEFAULT_TOOLS
+      MODE_BLOCKED_TOOLS = ACCESS_MODES.transform_values { |config| config[:blocked_tools] }.freeze
+
+      Approval = Data.define(
+        :tool_call_id, :tool_name, :arguments, :reason, :status,
+        :created_at, :approved_at, :tool_call
+      ) do
+        def pending?
+          status == :pending
+        end
+
+        def approved?
+          status == :approved
+        end
+
+        def [](key)
+          to_h.fetch(key.to_sym)
+        end
+      end
+
+      attr_reader :mode, :blocked_tools, :timeout
+
+      def initialize(mode: nil, blocked_tools: nil, timeout: nil, clock: nil)
+        @mode = mode
+        @blocked_tools =
+          if mode
+            mode_tools(mode)
+          elsif blocked_tools
+            Array(blocked_tools).map { |name| name.to_s.to_sym }.uniq
+          else
+            DEFAULT_BLOCKED_TOOLS.dup
+          end
+        @timeout = timeout
+        @clock = clock || -> { Time.now }
+        @approvals = {}
+        @mutex = Mutex.new
+      end
+
+      def before_tool_call(tool_call, _context = nil)
+        name = tool_call.name.to_s.to_sym
+        return { action: :proceed } unless blocked_tools.include?(name)
+
+        id = tool_call.id
+        created = false
+
+        result = @mutex.synchronize do
+          decision = existing_decision(id)
+          if decision
+            decision
+          else
+            created = true
+            record_pending(tool_call, name)
+          end
+        end
+
+        warn_approval(tool_call) if created
+        result
+      end
+
+      def approve(tool_call_id)
+        @mutex.synchronize do
+          entry = @approvals[tool_call_id]
+          next false unless entry
+
+          @approvals[tool_call_id] = entry.with(status: :approved, approved_at: @clock.call)
+          true
+        end
+      end
+
+      def pending_approvals
+        @mutex.synchronize { @approvals.values.select(&:pending?) }
+      end
+
+      private
+
+      def approved?(tool_call)
+        @mutex.synchronize do
+          existing_decision(tool_call.id)&.dig(:action) == :proceed
+        end
+      end
+
+      def mode_tools(mode)
+        config = ACCESS_MODES.fetch(mode) do
+          raise ArgumentError,
+                "Unknown access mode: #{mode.inspect}. Valid: #{ACCESS_MODES.keys.join(', ')}"
+        end
+        config[:blocked_tools].dup
+      end
+
+      def reason_for(tool_name)
+        return "#{tool_name} requires approval" if mode.nil?
+
+        "#{tool_name} requires approval (mode: #{mode})"
+      end
+
+      def expired?(entry)
+        return false if timeout.nil?
+
+        (@clock.call - entry.created_at) > timeout
+      end
+
+      def existing_decision(id)
+        entry = @approvals[id]
+
+        if entry && expired?(entry)
+          @approvals.delete(id)
+          entry = nil
+        end
+
+        return nil unless entry
+        return { action: :proceed } if entry.approved?
+
+        { action: :block, reason: entry.reason }
+      end
+
+      def record_pending(tool_call, name)
+        entry = Approval.new(
+          tool_call_id: tool_call.id,
+          tool_name: name,
+          arguments: tool_call.arguments,
+          reason: reason_for(name),
+          status: :pending,
+          created_at: @clock.call,
+          approved_at: nil,
+          tool_call: tool_call
+        )
+        @approvals[tool_call.id] = entry
+        { action: :block, reason: entry.reason }
+      end
+
+      def warn_approval(tool_call)
+        warn "[Permissions] Tool '#{tool_call.name}' requires approval. " \
+             "Call approve('#{tool_call.id}') to allow."
+      end
+    end
+  end
+end

data/lib/ask/permissions/tool_pattern.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Ask
+  module Permissions
+    # Matches declared rule patterns against tool names.
+    module ToolPattern
+      module_function
+
+      def match?(pattern, tool_name)
+        name = tool_name.to_s
+
+        case pattern
+        when :all then true
+        when Regexp then pattern.match?(name)
+        else pattern.to_s == name
+        end
+      end
+    end
+  end
+end

data/lib/ask/permissions/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  module Permissions
+    VERSION = '0.1.0'
+  end
+end

data/lib/ask/permissions.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'ask/permissions/version'
+require 'ask/permissions/errors'
+require 'ask/permissions/tool_pattern'
+require 'ask/permissions/permission_rules'
+require 'ask/permissions/approval_queue'
+require 'ask/permissions/permissions'
+require 'ask/permissions/approval_policy'

data/lib/ask-permissions.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'ask/permissions'

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: ask-permissions
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Provides framework-independent permission rules, policies, and approval
+  queues for ask-rb agents and integrations.
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- RELEASE.md
+- VERSIONING.md
+- lib/ask-permissions.rb
+- lib/ask/permissions.rb
+- lib/ask/permissions/approval_policy.rb
+- lib/ask/permissions/approval_queue.rb
+- lib/ask/permissions/errors.rb
+- lib/ask/permissions/permission_rules.rb
+- lib/ask/permissions/permissions.rb
+- lib/ask/permissions/tool_pattern.rb
+- lib/ask/permissions/version.rb
+homepage: https://github.com/ask-rb/ask-permissions
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ask-rb/ask-permissions
+  source_code_uri: https://github.com/ask-rb/ask-permissions/tree/master/lib
+  changelog_uri: https://github.com/ask-rb/ask-permissions/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.18
+specification_version: 4
+summary: Permission rules and approval workflows for ask-rb.
+test_files: []