cardinal-ai 0.2.20 → 0.2.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f598747488ba4b10c50dde4edca8d8d1bbad8561966950f8257d2d36d6855925
-  data.tar.gz: c197838268819214088cde422122e748684b6b3d0607f96eae69b5b140895b2b
+  metadata.gz: 5ccd0005599829484b375d90a86df2083d588f83cc3cc79a608b8ea95e54dbd9
+  data.tar.gz: 15926c269aa08cfb60446f12c7cf374d8d03876d2cbc55c6b78508aadd5bc4c3
 SHA512:
-  metadata.gz: abd46dd6087001a326abf6afa1d8530c66f445758d23a5646731482c5c7c246bd4bca345732518cf6408665f4c35ccc4ddaa49fd8dae1467ef9f175fb7b18890
-  data.tar.gz: c90684313c0e3a93125e6d8f2fa419013d4ed451e7cb255b74adf041998b5b8e28edcb13974cd5b7d88831a2641a41e36b7f924cd5c3114f5d6da34aa9b272bc
+  metadata.gz: 76322a4285ed47b9d60c2ceb7df46ae7bada9c0a49591ba9c348806324d947fd096f3e019334f737331ad44fdbda5b120cc162fbdabdfb0c046fa8a2de154e7b
+  data.tar.gz: '09ecec2c7b748a1b1d9441838cad40ca3b90e377cb5f61faa8bdef08ea5d662cc4b2de2f00c9cd76ae7e6c1724bce60881040aa1274efc6fadd73947bf207157'

data/app/assets/stylesheets/cardinal.css

@@ -176,6 +176,13 @@ a { color: var(--blue); text-decoration: none; }
 .share-status.share-err { color: var(--red); animation: none; }
 @keyframes share-fade { 0%, 70% { opacity: 1; } 100% { opacity: 0; } }
 
+/* Ask-first permission callouts (§ permissions) */
+.callout-permission { border-color: var(--amber); }
+.callout-permission.resolved { opacity: .75; }
+.perm-command { display: block; padding: 6px 8px; background: var(--surface); border-radius: 6px;
+                margin: 6px 0; overflow-wrap: anywhere; }
+.perm-actions { display: flex; gap: 8px; flex-wrap: wrap; margin: 8px 0 4px; }
+
 .pull-form { display: inline; }
 #repo-pull-status { font-size: 0.85rem; }
 #repo-pull-status .pull-ok  { color: var(--green); }

data/app/controllers/boards_controller.rb

@@ -29,9 +29,10 @@ class BoardsController < ApplicationController
 
   def update
     board = Board.first!
-    attrs = params.require(:board).permit(:name, :default_branch, :permission_bypass, archive_accepts_from: [])
+    attrs = params.require(:board).permit(:name, :default_branch, :permission_bypass, :permission_mode, archive_accepts_from: [])
     board.archive_accepts_from = attrs[:archive_accepts_from].to_a.map(&:to_s).reject(&:blank?) if attrs.key?(:archive_accepts_from)
     board.permission_bypass = (attrs[:permission_bypass] == "1") if attrs.key?(:permission_bypass)
+    board.settings["permission_mode"] = attrs[:permission_mode].presence_in(Board::PERMISSION_MODES) if attrs.key?(:permission_mode)
     board.update!(
       name: attrs[:name].presence || board.name,
       default_branch: attrs[:default_branch].presence || board.default_branch

data/app/controllers/columns_controller.rb

@@ -26,7 +26,7 @@ class ColumnsController < ApplicationController
       :name, :archetype, :instructions, :model, :effort,
       :concurrency_limit, :max_turns, :timeout_minutes, :plan_approval,
       :on_entry_text, :on_entry_json, :color, :custom_color, :arrivals, :ai,
-      :shell, :footer_text, accepts_from: []
+      :shell, :allowed_commands_text, :footer_text, accepts_from: []
     )
 
     policy = @column.policy.dup
@@ -39,6 +39,9 @@ class ColumnsController < ApplicationController
     policy["arrivals"] = attrs[:arrivals].presence_in(%w[top bottom])
     policy["ai"] = (attrs[:ai] == "1") if attrs.key?(:ai) # inbox forms omit it — never AI anyway
     policy["shell"] = (attrs[:shell] == "1") if attrs.key?(:shell) # worker shell access (execution gear only)
+    if attrs.key?(:allowed_commands_text)
+      policy["allowed_commands"] = attrs[:allowed_commands_text].to_s.lines.map(&:strip).reject(&:blank?).presence
+    end
     # Accept policy (card #15): store allowed source column ids as strings.
     # EXPLICIT ONLY — an empty list means the column accepts from nowhere.
     policy["accepts_from"] = attrs[:accepts_from].to_a.map(&:to_s).reject(&:blank?).presence

data/app/controllers/messages_controller.rb

@@ -5,11 +5,23 @@ class MessagesController < ApplicationController
     parked_run = card.runs.where(status: "needs_input").order(:id).last
     live_run = card.runs.where(status: "running").order(:id).last
 
+    pending_permission = live_run && live_run.permission_requests.pending.order(:id).first
+
     if params.dig(:message, :note) == "1"
       # Note only (card #47): on the record for any FUTURE reader — the next
       # column's assistant or worker sees it in conversation context — but no
       # AI is invoked now and no verdict changes. Type, drag, done.
       card.log!("user_message", actor: "user", text: text, note: true)
+    elsif pending_permission
+      # A chat reply while the agent waits on permission IS the verdict:
+      # a plain yes approves; anything else denies, with the user's words as
+      # the reason the agent reads (deny-with-reason is steering).
+      card.log!("user_message", actor: "user", run: live_run, text: text)
+      if text.strip.match?(/\A(y|yes|ok|okay|allow|approve|👍)\z/i)
+        pending_permission.resolve!("allowed")
+      else
+        pending_permission.resolve!("denied", message: text)
+      end
     elsif parked_run
       # Answer / plan feedback: goes back into the same agent session.
       kind = parked_run.phase == "plan" ? "user_message" : "answer"

data/app/controllers/permission_requests_controller.rb

@@ -0,0 +1,55 @@
+# The two faces of ask-first mode: the shim's API (create/show/auto-deny —
+# CSRF-exempt: it's a local process with no session) and the human's verdict
+# (answer, from timeline buttons).
+class PermissionRequestsController < ApplicationController
+  skip_before_action :verify_authenticity_token, only: [:create, :show, :answer]
+
+  def create
+    run = Run.find(params.require(:run_id))
+    input = params[:input].respond_to?(:to_unsafe_h) ? params[:input].to_unsafe_h : {}
+    request_row = run.permission_requests.create!(
+      tool_name: params.require(:tool_name), input: input,
+      command: input["command"].presence
+    )
+
+    if request_row.auto_allowed?
+      request_row.update!(status: "allowed", answered_at: Time.current)
+      run.card.log!("status_change", run: run, text: "🔐 Auto-approved #{request_row.describe} (pre-approved pattern)")
+    else
+      run.card.log!("permission_request", actor: "agent", run: run,
+                    request_id: request_row.id, tool: request_row.tool_name,
+                    command: request_row.command,
+                    text: "🔐 Wants to run #{request_row.describe}")
+      run.card.update!(status: "needs_input") if run.card.working?
+    end
+    render json: { id: request_row.id, status: request_row.status, message: request_row.message }
+  end
+
+  def show
+    request_row = PermissionRequest.find(params[:id])
+    # The blocked claude process is alive and waiting — the shim's poll is its
+    # proof of life for the sweeper.
+    request_row.run.update_columns(heartbeat_at: Time.current)
+    render json: { id: request_row.id, status: request_row.status, message: request_row.message }
+  end
+
+  def answer
+    request_row = PermissionRequest.find(params[:id])
+    if params[:auto] == "1"
+      request_row.resolve!("auto_denied", actor: "system")
+    elsif params[:verdict] == "allow"
+      request_row.resolve!("allowed", always: params[:always] == "1")
+    else
+      request_row.resolve!("denied", message: params[:message])
+    end
+
+    respond_to do |format|
+      format.turbo_stream do
+        render turbo_stream: turbo_stream.replace("permission_request_#{request_row.id}",
+          partial: "events/permission_request_state", locals: { request: request_row })
+      end
+      format.json { render json: { ok: true } }
+      format.html { redirect_to card_path(request_row.run.card) }
+    end
+  end
+end

data/app/models/board.rb

@@ -57,12 +57,20 @@ class Board < ApplicationRecord
   # button is always available; this governs only the drag affordance.
   store_accessor :settings, :archive_accepts_from, :permission_bypass
 
-  # Board default for worker autonomy (§ permissions): true (default) lets
-  # agents act without asking — full shell inside their workspace. false
-  # restricts workers to file tools (read/search/edit/write; Cardinal commits
-  # for them) unless a card explicitly overrides back to full autonomy.
+  # Board default for worker autonomy (§ permissions), three honest modes:
+  #   bypass     — agents act without asking (full shell)
+  #   ask        — shell commands pause for your 👍 in the card chat
+  #   restricted — file tools only; agents cannot execute anything
+  # (Back-compat: the earlier boolean permission_bypass=false maps to restricted.)
+  PERMISSION_MODES = %w[bypass ask restricted].freeze
+
+  def permission_mode_default
+    settings["permission_mode"].presence_in(PERMISSION_MODES) ||
+      (settings["permission_bypass"] == false ? "restricted" : "bypass")
+  end
+
   def permission_bypass?
-    settings["permission_bypass"] != false
+    permission_mode_default == "bypass"
   end
 
   def archive_accepts?(column)

data/app/models/card.rb

@@ -92,16 +92,16 @@ class Card < ApplicationRecord
   # default", so existing cards are unaffected. Read fresh at every segment
   # spawn (start, restart, resume) by the runner and the planning assistant, so
   # a change takes effect on the next segment — never on an already-running one.
-  # Permission override (nil = board default): "bypass" forces full autonomy
-  # for this card, "ask" forces the restricted file-tools mode.
-  PERMISSION_MODES = ["bypass", "ask"].freeze
+  # Permission override (nil = board default): bypass / ask / restricted —
+  # see Board::PERMISSION_MODES for what each means.
+  PERMISSION_MODES = Board::PERMISSION_MODES
+
+  def effective_permission_mode
+    permission_mode.presence_in(PERMISSION_MODES) || board.permission_mode_default
+  end
 
   def effective_permission_bypass?
-    case permission_mode
-    when "bypass" then true
-    when "ask"    then false
-    else board.permission_bypass?
-    end
+    effective_permission_mode == "bypass"
   end
 
   def effective_model  = model.presence || column.model

data/app/models/event.rb

@@ -5,7 +5,7 @@ class Event < ApplicationRecord
     question answer progress
     tool_call tool_result artifact_created
     run_started run_finished final_report error
-  ].freeze
+   permission_request].freeze
 
   # Which timeline zoom level an event first appears at (§7).
   CONVERSATION_KINDS = %w[user_message agent_message assistant_message question answer

data/app/models/permission_request.rb

@@ -0,0 +1,62 @@
+# One "may I run this?" from an agent in ask-first mode (§ permissions). The
+# claude process is ALIVE and blocked while this is pending — the MCP shim
+# polls for the verdict and the poll keeps the run's heartbeat fresh.
+class PermissionRequest < ApplicationRecord
+  STATUSES = %w[pending allowed denied auto_denied].freeze
+
+  belongs_to :run
+
+  validates :status, inclusion: { in: STATUSES }
+
+  scope :pending, -> { where(status: "pending") }
+
+  def pending? = status == "pending"
+
+  def describe
+    tool_name == "Bash" && command.present? ? "`#{command.truncate(120)}`" : tool_name
+  end
+
+  # The single verdict path — buttons, chat replies, and the shim's timeout
+  # all land here. `always` remembers the pattern for the rest of the run.
+  def resolve!(verdict, message: nil, always: false, actor: "user")
+    return unless pending?
+
+    update!(status: verdict, message: message.presence, answered_at: Time.current)
+    card = run.card
+
+    if verdict == "allowed" && always
+      pattern = tool_name == "Bash" ? command.to_s : tool_name
+      patterns = Array(run.briefing["allowed_patterns"]) | [pattern]
+      run.update!(briefing: run.briefing.merge("allowed_patterns" => patterns))
+    end
+
+    text =
+      case verdict
+      when "allowed"     then "🔐 Approved #{describe}#{" — and anything matching it for the rest of this run" if always}"
+      when "auto_denied" then "🔐 #{describe} auto-denied (no answer in time) — the agent was told to adapt or park"
+      else                    "🔐 Denied #{describe}#{": “#{message}”" if message.present?}"
+      end
+    card.log!("status_change", actor: actor, run: run, text: text)
+    card.update!(status: "working") if card.needs_input? && run.permission_requests.pending.none?
+    broadcast_resolution
+  end
+
+  # Does an existing pattern (column pre-approved list or earlier
+  # allow-for-this-run) already cover this request?
+  def auto_allowed?
+    patterns = Array(run.card.column.policy["allowed_commands"]) + Array(run.briefing["allowed_patterns"])
+    if tool_name == "Bash"
+      patterns.any? { |p| p.present? && command.to_s.start_with?(p.strip) }
+    else
+      patterns.map(&:strip).include?(tool_name)
+    end
+  end
+
+  private
+
+  # Re-render the timeline callout everywhere (buttons → resolved line).
+  def broadcast_resolution
+    broadcast_replace_to run.card, target: "permission_request_#{id}",
+                         partial: "events/permission_request_state", locals: { request: self }
+  end
+end

data/app/models/run.rb

@@ -4,6 +4,7 @@ class Run < ApplicationRecord
   belongs_to :agent_session
   has_one :card, through: :agent_session
   has_many :artifacts, dependent: :destroy
+  has_many :permission_requests, dependent: :destroy
   has_many :events, dependent: :nullify
 
   enum :status, STATUSES.index_by(&:itself)

data/app/services/agent/runner.rb

@@ -45,6 +45,23 @@ module Agent
       - Finish with a concise report: what you did, what to check, any open questions.
     RULES
 
+    # Ask-first mode: full toolset, but shell commands pause for the user's
+    # approval (routed through the Cardinal permission shim).
+    ASK_EXECUTE_RULES = <<~RULES.freeze
+      ## Rules
+      - You have the full toolset, but shell commands PAUSE for the user's approval.
+        A denial comes with their reason — adapt to it rather than retrying the same thing.
+      - Approvals can take a while; the user may also pre-approve a pattern so similar
+        commands run without asking again.
+      - Work only inside this repository checkout (you are already on the card's branch).
+      - Commit your work as you go with clear messages (commits need approval like any
+        command). Do NOT push — the runner pushes for you.
+      - Stay strictly within the card's scope. Prefer the smallest reasonable interpretation and note assumptions.
+      - If denials leave you genuinely blocked, output a single line starting with
+        "QUESTION:" followed by the question, then stop immediately.
+      - Finish with a concise report: what you did, what to check, any open questions.
+    RULES
+
     def self.start(run) = new(run).start
     def self.resume(run, message, approve: false) = new(run).resume(message, approve: approve)
 
@@ -113,8 +130,17 @@ module Agent
       workspace = resuming ? Workspace.attach(card) : Workspace.provision(card)
       remember_base_sha(workspace) if mode == "execute"
 
-      cmd = ["claude", "-p", prompt, "--output-format", "stream-json", "--verbose",
-             "--permission-mode", "bypassPermissions"]
+      cmd = ["claude", "-p", prompt, "--output-format", "stream-json", "--verbose"]
+      if ask_mode? && mode != "plan" && mode != "plan_wrap"
+        # Ask-first: permission requests route to our MCP shim, which parks
+        # them on the card for a chat/button verdict. The claude process
+        # stays alive, blocked, until the answer arrives.
+        cmd += ["--permission-mode", "default",
+                "--permission-prompt-tool", "mcp__cardinal__permission",
+                "--mcp-config", permission_shim_config]
+      else
+        cmd += ["--permission-mode", "bypassPermissions"]
+      end
       case mode
       when "plan"
         # Read-only exploration for the plan phase. (--permission-mode plan
@@ -147,7 +173,17 @@ module Agent
         run.agent_session.update!(status: "ready", config: run.agent_session.config.merge("pid" => wait.pid))
         timeout_min = (column.timeout_minutes.presence || 30).to_i
         watchdog = Thread.new do
-          sleep timeout_min * 60
+          deadline = Time.current + timeout_min * 60
+          loop do
+            sleep 15
+            # Waiting on a human is not running away — a pending permission
+            # request resets the clock instead of counting against it.
+            waiting = ActiveRecord::Base.connection_pool.with_connection do
+              PermissionRequest.where(run_id: run.id, status: "pending").exists?
+            end
+            deadline = Time.current + timeout_min * 60 if waiting
+            break if Time.current > deadline
+          end
           @timed_out = true
           Process.kill("TERM", wait.pid) rescue nil
         end
@@ -381,14 +417,37 @@ module Agent
     end
 
     def execute_rules
-      restricted_tools? ? RESTRICTED_EXECUTE_RULES : EXECUTE_RULES
+      return RESTRICTED_EXECUTE_RULES if restricted_tools?
+      ask_mode? ? ASK_EXECUTE_RULES : EXECUTE_RULES
+    end
+
+    # Ask-first applies when resolved mode is "ask" and the column's shell
+    # toggle hasn't already restricted the agent to file tools.
+    def ask_mode?
+      column.shell_access? && card.effective_permission_mode == "ask"
+    end
+
+    def permission_shim_config
+      {
+        mcpServers: {
+          cardinal: {
+            command: RbConfig.ruby,
+            args: [Rails.root.join("lib", "cardinal", "permission_shim.rb").to_s],
+            env: {
+              "CARDINAL_URL" => "http://127.0.0.1:#{ENV.fetch("PORT", "3000")}",
+              "CARDINAL_RUN_ID" => run.id.to_s,
+              "CARDINAL_PERMISSION_TIMEOUT" => "600"
+            }
+          }
+        }
+      }.to_json
     end
 
     # Three voices, one verdict: the column's shell toggle, the board's
     # permission default, and the card's own override (which beats the board
     # but never re-opens a column that turned shell off).
     def restricted_tools?
-      !column.shell_access? || !card.effective_permission_bypass?
+      !column.shell_access? || card.effective_permission_mode == "restricted"
     end
 
     def plan_prompt

data/app/views/boards/edit.html.erb

@@ -17,11 +17,12 @@
           <label>Default branch <%= info_tip("The branch agents fork card branches from and Done merges pull requests toward. Detected from the repo at first boot; fix it here if that guess was wrong.") %></label>
           <%= f.text_field :default_branch, placeholder: "main" %>
 
-          <label class="check-row">
-            <%= f.check_box :permission_bypass, { checked: @board.permission_bypass? }, "1", "0" %>
-            Agents act without asking (full autonomy)
-            <%= info_tip("On (default): worker agents run shell commands — tests, builds, git — inside their workspace without permission prompts. Off: workers get file tools only (read, search, edit, write); they cannot execute anything, and Cardinal commits their edits for them. Each card can override this in its 🧠 panel; a column whose Shell access is off stays restricted regardless.") %>
-          </label>
+          <label>Agent permissions <%= info_tip("Full autonomy (default): workers run shell commands without asking. Ask first: every command pauses on the card — approve with a button or a chat reply; pre-approve patterns per column or per run. File tools only: workers cannot execute anything; Cardinal commits their edits. Each card can override this in its 🧠 panel; a column whose Shell access is off stays restricted regardless.") %></label>
+          <%= f.select :permission_mode,
+                [["Full autonomy — agents act without asking", "bypass"],
+                 ["Ask first — commands pause for your 👍 on the card", "ask"],
+                 ["File tools only — agents cannot execute anything", "restricted"]],
+                selected: @board.permission_mode_default %>
         <% end %>
 
         <label>Repository</label>

data/app/views/cards/_detail.html.erb

@@ -180,9 +180,10 @@
                   <div>
                     <label>Permissions <%= info_tip("Overrides the board's autonomy default for THIS card. Full autonomy: the worker runs shell commands without asking. Restricted: file tools only — it cannot execute anything, and Cardinal commits its edits. A column whose Shell access is off stays restricted regardless.") %></label>
                     <%= f.select :permission_mode,
-                          [["Board default (#{@card.board.permission_bypass? ? "full autonomy" : "restricted"})", ""],
+                          [["Board default (#{{ "bypass" => "full autonomy", "ask" => "ask first", "restricted" => "file tools only" }[@card.board.permission_mode_default]})", ""],
                            ["Full autonomy — acts without asking", "bypass"],
-                           ["Restricted — file tools only", "ask"]],
+                           ["Ask first — commands pause for your 👍", "ask"],
+                           ["File tools only — cannot execute", "restricted"]],
                           selected: @card.permission_mode.to_s %>
                   </div>
                 </div>

data/app/views/columns/edit.html.erb

@@ -111,6 +111,11 @@
                 Shell access — the agent may run commands (tests, builds, git)
                 <%= info_tip("Unchecked: the agent gets file tools only (read, search, edit, write) and physically cannot execute anything — Cardinal commits and pushes its edits for it. Safer, but it can't run your tests or generators, and the agent process runs on this machine either way.") %>
               </label>
+
+              <label>Pre-approved commands <%= info_tip("Only matters in ask-first permission mode: commands starting with any line here run WITHOUT asking. One pattern per line — e.g. \"bundle exec rails test\" or \"git commit\". Everything else still pauses for your verdict.") %></label>
+              <%= f.text_area :allowed_commands_text, rows: 2, class: "mono",
+                    value: Array(@column.policy["allowed_commands"]).join("\n"),
+                    placeholder: "bundle exec rails test\ngit commit" %>
             <% end %>
 
             </div>

data/app/views/events/_event.html.erb

@@ -3,6 +3,11 @@
     <span><%= event.payload["from"] %> → <%= event.payload["to"] %></span>
     <time><%= event.created_at.strftime("%b %-d %H:%M") %></time>
   </div>
+<% elsif event.kind == "permission_request" %>
+  <% request = PermissionRequest.find_by(id: event.payload["request_id"]) %>
+  <% if request %>
+    <%= render "events/permission_request_state", request: request %>
+  <% end %>
 <% elsif event.kind == "move_rejected" %>
   <div class="move-rejected-row">
     <span>⤺ <%= event.text %></span>

data/app/views/events/_permission_request_state.html.erb

@@ -0,0 +1,17 @@
+<div id="permission_request_<%= request.id %>" class="panel-callout callout-permission<%= " resolved" unless request.pending? %>">
+  <% if request.pending? %>
+    <p><strong>🔐 The agent wants to run:</strong></p>
+    <p><code class="perm-command"><%= request.describe %></code></p>
+    <div class="perm-actions">
+      <%= button_to "✅ Allow", answer_permission_request_path(request, verdict: "allow"), class: "approve-btn" %>
+      <%= button_to "✅ Allow similar for this run", answer_permission_request_path(request, verdict: "allow", always: "1"),
+            class: "theme-toggle", title: "Also pre-approves anything starting with this command for the rest of the run" %>
+      <%= button_to "❌ Deny", answer_permission_request_path(request, verdict: "deny"), class: "cancel-btn" %>
+    </div>
+    <p class="hint">Or reply in the chat: “yes” approves — anything else denies, with your words as the reason the agent reads.</p>
+  <% else %>
+    <p>🔐 <%= request.describe %> —
+      <strong><%= { "allowed" => "approved", "denied" => "denied", "auto_denied" => "auto-denied (no answer in time)" }[request.status] %></strong><%= " · “#{request.message}”" if request.message.present? %>
+    </p>
+  <% end %>
+</div>

data/config/boot.rb

@@ -6,6 +6,19 @@
 #     belong in an installed gem directory).
 if ENV["CARDINAL_GEM"] == "1"
   require "rubygems"
+  # Activate our own gem up front: bare `require`s pick the newest installed
+  # version of each dependency, ignoring the gemspec's constraints — in a
+  # shared gemset (host app + cardinal) that can activate a version we don't
+  # support. Activating cardinal-ai pins the whole tree to the gemspec.
+  begin
+    require_relative "../lib/cardinal/version"
+    gem "cardinal-ai", Cardinal::VERSION
+  rescue Gem::LoadError
+    # Checkout run with CARDINAL_GEM=1 but no installed gem — requires below
+    # fall back to newest-installed. A missing/conflicting DEPENDENCY of an
+    # installed gem must surface here, not as a NameError deep in the app.
+    raise unless Gem::Specification.find_all_by_name("cardinal-ai").empty?
+  end
 else
   ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
   require "bundler/setup" # Set up gems listed in the Gemfile.

data/config/routes.rb

@@ -21,6 +21,10 @@ Rails.application.routes.draw do
     end
     resources :messages, only: [:create]
   end
+  resources :permission_requests, only: [:create, :show] do
+    member { post :answer }
+  end
+
   get  "asana/new"        => "asana#new_card",   as: :asana_new_card
   post "asana/connect"    => "asana#connect",    as: :asana_connect
   post "asana/import"     => "asana#import",     as: :asana_import

data/db/migrate/20260706141319_create_permission_requests.rb

@@ -0,0 +1,16 @@
+# Ask-first permission mode: one row per "may I run this?" from an agent.
+class CreatePermissionRequests < ActiveRecord::Migration[8.1]
+  def change
+    create_table :permission_requests do |t|
+      t.references :run, null: false, foreign_key: true
+      t.string :tool_name, null: false
+      t.text :command                 # Bash command text, for display + pattern matching
+      t.json :input, default: {}
+      t.string :status, null: false, default: "pending" # pending/allowed/denied/auto_denied
+      t.text :message                 # denial reason shown to the agent
+      t.datetime :answered_at
+      t.datetime :created_at, null: false
+    end
+    add_index :permission_requests, [:run_id, :status]
+  end
+end

data/lib/cardinal/permission_shim.rb

@@ -0,0 +1,112 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Cardinal's permission shim (§ ask-first mode): a minimal MCP stdio server
+# the claude CLI calls via --permission-prompt-tool. Each permission request
+# becomes a PermissionRequest on the card (POST to the local Cardinal server);
+# we then poll for the human's verdict — the poll doubles as the run's
+# heartbeat — and hand claude back allow/deny. Pure stdlib; fails CLOSED
+# (deny) on any transport error.
+require "json"
+require "net/http"
+require "uri"
+
+class CardinalPermissionShim
+  PROTOCOL = "2024-11-05"
+
+  def initialize(input: $stdin, output: $stdout,
+                 base_url: ENV["CARDINAL_URL"], run_id: ENV["CARDINAL_RUN_ID"],
+                 timeout: ENV.fetch("CARDINAL_PERMISSION_TIMEOUT", "600").to_i)
+    @input, @output = input, output
+    @base_url, @run_id, @timeout = base_url, run_id, timeout
+    @output.sync = true
+  end
+
+  def run
+    while (line = @input.gets)
+      line = line.strip
+      next if line.empty?
+      handle(JSON.parse(line))
+    end
+  rescue Interrupt
+    nil
+  end
+
+  def handle(msg)
+    case msg["method"]
+    when "initialize"
+      reply(msg["id"], protocolVersion: msg.dig("params", "protocolVersion") || PROTOCOL,
+                       capabilities: { tools: {} },
+                       serverInfo: { name: "cardinal", version: "1.0" })
+    when "tools/list"
+      reply(msg["id"], tools: [{
+        name: "permission",
+        description: "Ask the Cardinal board's user to approve or deny a tool use.",
+        inputSchema: { type: "object",
+                       properties: { tool_name: { type: "string" }, input: { type: "object" } },
+                       required: ["tool_name"] }
+      }])
+    when "tools/call"
+      args = msg.dig("params", "arguments") || {}
+      decision = decide(args)
+      reply(msg["id"], content: [{ type: "text", text: decision.to_json }])
+    when "ping"
+      reply(msg["id"], {})
+    else
+      reply(msg["id"], {}) if msg["id"] # politely ack anything else that expects an answer
+    end
+  end
+
+  # POST the request, poll until answered, translate to the CLI's contract.
+  def decide(args)
+    created = post("/permission_requests",
+                   run_id: @run_id, tool_name: args["tool_name"].to_s, input: args["input"] || {})
+    return deny("Cardinal couldn't record the permission request — denied for safety.") unless created
+
+    waited = 0
+    status, message = created["status"], created["message"]
+    while status == "pending"
+      if waited >= @timeout
+        post("/permission_requests/#{created["id"]}/answer", verdict: "deny", auto: "1")
+        return deny("No answer from the user in time. Work around this without the command, or park with a QUESTION:.")
+      end
+      sleep 2
+      waited += 2
+      current = get("/permission_requests/#{created["id"]}")
+      status, message = current["status"], current["message"] if current
+    end
+
+    if status == "allowed"
+      { "behavior" => "allow", "updatedInput" => args["input"] || {} }
+    else
+      deny(message.to_s.empty? ? "The user denied this action." : "The user denied this: #{message}")
+    end
+  end
+
+  def deny(message) = { "behavior" => "deny", "message" => message }
+
+  def reply(id, payload)
+    @output.puts({ jsonrpc: "2.0", id: id, result: payload }.to_json)
+  end
+
+  def post(path, body)
+    http_json(Net::HTTP::Post, path, body)
+  end
+
+  def get(path)
+    http_json(Net::HTTP::Get, path, nil)
+  end
+
+  def http_json(klass, path, body)
+    uri = URI("#{@base_url}#{path}")
+    req = klass.new(uri.request_uri, "Content-Type" => "application/json", "Accept" => "application/json")
+    req.body = body.to_json if body
+    res = Net::HTTP.start(uri.host, uri.port, open_timeout: 5, read_timeout: 10) { |h| h.request(req) }
+    res.code.to_i.between?(200, 299) ? JSON.parse(res.body) : nil
+  rescue StandardError => e
+    warn "cardinal-shim: #{e.class}: #{e.message}"
+    nil
+  end
+end
+
+CardinalPermissionShim.new.run if __FILE__ == $PROGRAM_NAME

data/lib/cardinal/version.rb

@@ -1,3 +1,3 @@
 module Cardinal
-  VERSION = "0.2.20"
+  VERSION = "0.2.22"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cardinal-ai
 version: !ruby/object:Gem::Version
-  version: 0.2.20
+  version: 0.2.22
 platform: ruby
 authors:
 - Jason Ellis
@@ -27,16 +27,16 @@ dependencies:
   name: propshaft
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -69,44 +69,44 @@ dependencies:
   name: importmap-rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: turbo-rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: stimulus-rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: redcarpet
   requirement: !ruby/object:Gem::Requirement
@@ -168,6 +168,7 @@ files:
 - app/controllers/cards_controller.rb
 - app/controllers/columns_controller.rb
 - app/controllers/messages_controller.rb
+- app/controllers/permission_requests_controller.rb
 - app/controllers/runs_controller.rb
 - app/helpers/application_helper.rb
 - app/javascript/application.js
@@ -207,6 +208,7 @@ files:
 - app/models/column.rb
 - app/models/concerns/model_labeling.rb
 - app/models/event.rb
+- app/models/permission_request.rb
 - app/models/run.rb
 - app/services/agent/runner.rb
 - app/services/agent/workspace.rb
@@ -234,6 +236,7 @@ files:
 - app/views/columns/_column.html.erb
 - app/views/columns/edit.html.erb
 - app/views/events/_event.html.erb
+- app/views/events/_permission_request_state.html.erb
 - app/views/layouts/application.html.erb
 - app/views/layouts/mailer.html.erb
 - app/views/layouts/mailer.text.erb
@@ -281,11 +284,13 @@ files:
 - db/migrate/20260705193935_add_settings_to_boards.rb
 - db/migrate/20260705225451_add_asana_url_to_cards.rb
 - db/migrate/20260706002904_add_permission_mode_to_cards.rb
+- db/migrate/20260706141319_create_permission_requests.rb
 - db/queue_schema.rb
 - db/seeds.rb
 - docker/agent/Dockerfile
 - exe/cardinal
 - lib/cardinal.rb
+- lib/cardinal/permission_shim.rb
 - lib/cardinal/version.rb
 - public/400.html
 - public/404.html