kairos-chain 3.88.1 → 3.89.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c37ee945277e2917d116b02aeb8b47957f97363d8428aae7b54e17a732ca0d94
-  data.tar.gz: 62df9a6d5f05afd01c3aae950959d6398a22e979270183a154e4fd211d2b78c8
+  metadata.gz: 109c03e66d55828499533b9d00945390f97cfd8aa56376aa898c099a30218316
+  data.tar.gz: 3013372fe35ae2bf4e3e5a4267fed64197e7480da32f2030664eb61766724f44
 SHA512:
-  metadata.gz: 74101139a4c243c77119530a5a723c0e1de9fdb6224c1b5f776f78b250040c1e4aade60b93cb75d5cbef3afac2609e2832763a079fc38bddd6ecac84e73f2c32
-  data.tar.gz: 0bf5337f8e6b5985967711300dfe64554e7ff55bb67f7f1dff1d3fca1aefa28fa74677477d5ed3c32cc9b843556434ca692a7254d26a74d68a32807408091621
+  metadata.gz: 824d9d93d7e2c22a991e116a2f8c66acf8d54ecb2469a541c2f51a0ae982b0018d2650f88931daa5cf6da2091bba5ed470e13334c7b341d09fdfa2a7f48c01f8
+  data.tar.gz: bcc18d3c8123b54db6b934fc475f8517a7cd3dc2562a34d213c37140f08b45218d461c3685216f6577e9683de111f7ec70a07f9da27e5bfe947d0e740caffc5f

data/CHANGELOG.md

@@ -4,6 +4,116 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.89.0] - 2026-10-07
+
+### Security — agent: the act route runs from an allow-list
+
+The 3.88.x act route refused tools by name, and every review round found
+another tool, route or path nobody had named. **The act route now runs a step
+only if the act-route table classifies its tool.** Every other step is set
+aside — with the steps that depend on it — and handed to the operator as
+`awaiting_operator` at the end of the cycle, in manual and autonomous mode.
+
+**After upgrading, the act route runs nothing until you rule the table into
+force, at a terminal:**
+
+    ruby .kairos/skillsets/agent/bin/agent_rule.rb status
+    ruby .kairos/skillsets/agent/bin/agent_rule.rb activate
+
+`activate` shows the tools and asks you to type back a nonce; it refuses to run
+without a terminal. The ruling goes on the chain. The table
+(`agent/lib/agent/act_classification.yml`) is in force only while the latest
+ruling names the SHA-256 of its exact bytes, so an upgrade that changes it, a
+`withdraw`, or an edit empties the act route again until you rule. Every agent
+response says under `classification` whether the table is in force.
+
+- **Base table**: read-only tools, `context_save`, `operator_report`,
+  sandboxed `llm_call`, and `safe_file_write` / `safe_file_edit` /
+  `safe_file_copy`.
+- **Work-tree writes are allowed by place**: a plain relative path under
+  `docs/drafts/`, a file named `draft_*` ending `.md` or `.txt`, no hidden
+  segment and no `workspace_root` argument — checked as written and as
+  resolved. Any other write is set aside. With the guard on, every work-tree
+  write is set aside.
+- **No step may name a hidden (dot) path, a leading `~`, a control character,
+  `keys/` or a private-key file** (`.pem`, `.key`, `.p12`, `.pfx`, `id_rsa`, …),
+  reads included; `.git`, `.github`, `.vscode`, `.cursor`, `.gemini` and
+  `.envrc` join the protected locations.
+- **The file route (`agent_execute`) is no longer taken.** Its tools cannot be
+  classified.
+- **Risk**: the risk gate and the act read the same classified plan. A step's
+  risk is the table's, raised (never lowered) by the plan's own label or
+  `risk_default`; an unknown label counts as high.
+- DECIDE is told which tools run and where writes may land.
+
+Still open: secret files with visible names (e.g. `credentials.json`) are
+readable by `safe_file_read`; a read-place allow-list needs per-instance table
+extensions and comes later. Do not run the agent unattended until approval
+delegation lands.
+
+## [3.88.2] - 2026-10-06
+
+### Security — agent: the act and its LLM bodies stay inside their gates
+
+A design review of approval delegation found several ways for the agent to get
+around the gates it runs inside: the tool blacklist, the risk budget and the
+guard. Each was confirmed in code; none was observed in use. Four review rounds
+followed. **The act route is still deny-based. Do not run the agent unattended
+until an act-route allow-list lands** (next version, designed with approval
+delegation).
+
+**No LLM body launched for the agent carries tools in the project root.**
+- **Agent phases.** ORIENT, DECIDE, REFLECT and the persona reviews launched
+  `claude -p` in the project root. It read the project's instruction files and
+  inherited its permission rules (on one instance, `Bash(*)`, `Write` and
+  `Edit`). Every agent LLM call is now sandboxed.
+- **llm_call steps in the act.** The driver forces `sandbox_mode` on them. A
+  step whose provider carries tools (codex, cursor, codex_mcp), or any provider
+  outside claude_code / anthropic / openai / bedrock, is refused before the
+  act. This includes the instance's default provider when the step names
+  none, and the default provider used by `write_section`.
+- **`write_section`.** Its section writer now always calls the LLM sandboxed.
+- **multi_llm_review cursor seat.** It ran `agent -p` (every tool, write and
+  shell included) in the server's working directory. It now runs
+  `agent -p --trust --mode plan` (read-only) in an empty directory made for
+  each call. Cursor reviews therefore see only the artifact.
+
+**An act does not touch what constrains the agent or its operator.**
+- **Protected locations.** A step whose path arguments, at any depth and
+  whatever the tool, reach a protected location is refused before ACT. The
+  protected locations are:
+  - the KairosChain stores (`.kairos`: config, sessions, L1, the instruction
+    mode, the chain, the keys);
+  - `.claude` and `.codex`;
+  - `.mcp.json`, `CLAUDE.md` and `AGENTS.md`;
+  - anything outside the project (`$HOME` and `/` never count as the
+    project).
+- **How paths are judged.** Paths are resolved against the step's own root
+  arguments and against the tools' default roots, so a decoy root cannot move
+  the check. `..` segments, unresolvable paths and dangling symlinks are
+  refused. A symlink is judged by its target.
+- **Recording.** The refusal is recorded on the chain (`agent_act_refused`,
+  with the rule that fired) whether or not the guard is on.
+- **Record-store writers** (`chain_record`, attestation and state commits) are
+  now refused on the act route with the guard off as well. The record judges
+  the act, so the act may not write it.
+- **Configuration writers** (`llm_configure`, `mode_hooks_add` /
+  `mode_hooks_project`, `plugin_project`), `hermes_*` and `multi_llm_review*`
+  are refused on the act route. All of these are also hidden from DECIDE's
+  tool catalog, and DECIDE's norms name the rule.
+- **Instances whose `safety.yml` sets no `safe_root`.** The file tools resolve
+  relative paths inside the stores there, so the act refuses them. The refusal
+  says to set `safe_root`.
+
+**Not covered yet.**
+- `.git/hooks` and `.git/config`, `.cursor*`, `.gemini`,
+  `.github/copilot-instructions.md`, `.envrc` and `.vscode/tasks.json` are not
+  in the protected set.
+- A path-less tool not named above is not stopped (the allow-list will).
+- `agent_execute` remains unregistered.
+- In an operator's own multi_llm_review runs, the codex seat can still read
+  the repository.
+
 ## [3.88.1] - 2026-10-06
 
 ### Fixed — agent guard: the verdict reaches the record

data/lib/kairos_mcp/version.rb

@@ -1,4 +1,4 @@
 module KairosMcp
-  VERSION = "3.88.1"
+  VERSION = "3.89.0"
   CHANGELOG_URL = "https://github.com/masaomi/KairosChain_2026/blob/main/CHANGELOG.md"
 end

data/templates/skillsets/agent/bin/agent_rule.rb

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# The operator's terminal ruling on the agent's act-route allow-list
+# (design v0.3, INV-A2 / INV-D8).
+#
+#   ruby .kairos/skillsets/agent/bin/agent_rule.rb activate   # rule the current table into force
+#   ruby .kairos/skillsets/agent/bin/agent_rule.rb withdraw   # take it out of force
+#   ruby .kairos/skillsets/agent/bin/agent_rule.rb status     # show what is in force (records nothing)
+#
+# Options: --data-dir DIR   the instance data dir whose chain is written
+#                           (default: the .kairos this script is installed in)
+#
+# activate and withdraw read a nonce typed back at /dev/tty and refuse to run
+# without a terminal. That keeps an MCP call from producing a ruling through
+# this path. It does not prove a person typed: any process that can start
+# programs can open a pseudo-terminal, read the nonce and type it back (shown
+# in review, 2026-10-06), and such a process can write the chain directly
+# anyway. 'attested' therefore records the path the ruling came by, not who
+# was at the keyboard (INV-D8 boundary; the constrained party is the agent).
+
+require 'json'
+
+action = ARGV.find { |a| %w[activate withdraw status].include?(a) }
+abort 'usage: agent_rule.rb activate|withdraw|status [--data-dir DIR]' unless action
+
+idx = ARGV.index('--data-dir')
+data_dir = idx ? File.expand_path(ARGV[idx + 1].to_s) : File.expand_path('../../..', __dir__)
+abort "no data dir at #{data_dir}" unless File.directory?(data_dir)
+
+$LOAD_PATH.unshift(ENV['KAIROS_SERVER_LIB']) if ENV['KAIROS_SERVER_LIB']
+begin
+  require 'kairos_mcp'
+  require 'kairos_mcp/kairos_chain/chain'
+rescue LoadError => e
+  abort "cannot load kairos_mcp (#{e.message}); install the kairos-chain gem or set KAIROS_SERVER_LIB"
+end
+KairosMcp.data_dir = data_dir
+
+lib = File.expand_path('../lib', __dir__)
+require File.join(lib, 'agent', 'admission')
+require File.join(lib, 'agent', 'mandate_adapter')
+require File.join(lib, 'agent', 'act_classification')
+ac = KairosMcp::SkillSets::Agent::ActClassification
+path = ac::BASE_PATH
+
+puts "Data dir: #{data_dir}"
+if action == 'status'
+  eff = ac.load_effective(path: path)
+  puts "Table #{ac::TABLE_ID}: #{eff['status']}"
+  puts "  file sha256:  #{eff['sha256']}"
+  puts "  ruled sha256: #{eff['ruled_sha256'] || '(none)'}"
+  puts "  detail: #{eff['detail']}" if eff['detail']
+  puts "  tools in force: #{eff['tools'].keys.sort.join(', ')}" unless eff['tools'].empty?
+  exit 0
+end
+
+tty = begin
+  File.open('/dev/tty', 'r+')
+rescue StandardError => e
+  abort "#{action} needs a terminal (/dev/tty: #{e.class}). Run it yourself in a terminal."
+end
+
+begin
+  result = ac.interactive_rule(action: action, tty_in: tty, tty_out: tty, path: path)
+ensure
+  tty.close
+end
+exit(result['recorded'] ? 0 : 1)

data/templates/skillsets/agent/lib/agent/act_classification.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+require 'digest'
+require 'securerandom'
+require 'time'
+
+module KairosMcp
+  module SkillSets
+    module Agent
+      # The act route's allow-list (design v0.3, INV-A1 / INV-A2).
+      #
+      # A step runs on the act route only if its tool is in the effective
+      # classification table. Every other step is set aside for the operator,
+      # the way a step marked requires_human_cognition is.
+      #
+      # The table is a norm, so it is in force only by an operator act: the
+      # latest attested ruling for the table must name the sha256 of the file's
+      # bytes. A missing ruling, a withdrawal, a mismatch, or a table that fails
+      # validation all yield the empty table — nothing classified, every step
+      # to the operator. This includes the base table shipped with the gem: an
+      # upgrade that changes its bytes leaves the act route empty until the
+      # operator rules on the new hash.
+      #
+      # Attestation boundary (INV-D8): a ruling is attested when it was entered
+      # at the operator's terminal (see .interactive_rule). Any party that can
+      # write the chain or the stores — an MCP caller, the calling session, a
+      # shell — could write a block of the same shape. The constrained party is
+      # the agent, which cannot: its act route denies record-store writers and
+      # protected locations, and the file route is not reachable.
+      module ActClassification
+        TABLE_ID = 'act_classification'
+        RULING_KIND = 'agent_table_ruling'
+        BASE_PATH = File.expand_path('act_classification.yml', __dir__)
+
+        # Effect classes a table may admit, and the risk each carries. Anything
+        # else (L0, record-store, irreversible, outward) is not admissible.
+        EFFECT_RISK = {
+          'read_only' => 'low',
+          'session_record' => 'low',
+          'llm_sandboxed' => 'low',
+          'reversible_local' => 'medium'
+        }.freeze
+
+        # Effects that land in the live tree. Under the guard those belong to
+        # the confined route (AGT-1), which is not wired, so they are set aside.
+        # Without the guard they are classified only for a step whose every
+        # location lands inside the table's write_roots with one of its
+        # write_extensions (design v0.3 §6.5 as ruled 2026-10-06): writes are
+        # allowed by place, because refusing by place — naming each location
+        # a tool executes — did not close (implementation review R1 found an
+        # editor add-on path the name list missed).
+        LIVE_TREE_EFFECTS = %w[reversible_local].freeze
+
+        RISK_ORDER = %w[low medium high].freeze
+
+        # Names a table may never admit, whatever their class: the tools the
+        # 3.88.2 deny-lists refuse, the L0/L1 store writers, and the file
+        # route's tools (classification precedes routing: no route is reachable
+        # through a tool this table cannot name).
+        def self.forbidden_patterns
+          adm = ::KairosMcp::SkillSets::Agent::Admission
+          adm::RECORD_STORE_TOOLS + adm::ACT_CONFIG_WRITERS + adm::LAYER_WRITE_TOOLS.values.flatten +
+            ::KairosMcp::SkillSets::Agent::MandateAdapter::FILE_TOOL_NAMES
+        end
+
+        module_function
+
+        def sha256_of(path)
+          Digest::SHA256.hexdigest(File.binread(path))
+        end
+
+        # Ruling records in chain order, from blocks whose data is an array of
+        # strings. Entries that are not JSON objects of the ruling kind are
+        # skipped.
+        def rulings_from_blocks(blocks)
+          Array(blocks).flat_map do |block|
+            data = block.respond_to?(:data) ? block.data : (block['data'] || block[:data])
+            Array(data).filter_map do |entry|
+              rec = entry.is_a?(String) ? (JSON.parse(entry) rescue nil) : entry
+              rec if rec.is_a?(Hash) && rec['kind'] == RULING_KIND
+            end
+          end
+        end
+
+        # Where rulings are read from. nil in production (the instance chain).
+        # Tests set a callable returning [rulings, error], built from blocks the
+        # real interactive_rule appended to an in-memory chain.
+        class << self
+          attr_accessor :rulings_source
+        end
+
+        # [rulings, nil] from the instance chain, or [[], reason] when the
+        # chain cannot be read (which empties the table).
+        def chain_rulings
+          return ActClassification.rulings_source.call if ActClassification.rulings_source
+
+          require 'kairos_mcp/kairos_chain/chain'
+          chain = ::KairosMcp::KairosChain::Chain.new
+          state = chain.load_state
+          return [[], "chain #{state}"] unless %i[readable absent].include?(state)
+
+          [rulings_from_blocks(chain.chain), nil]
+        rescue StandardError, ScriptError => e
+          [[], "chain unreadable: #{e.class}: #{e.message[0, 120]}"]
+        end
+
+        # The effective table: { 'status', 'sha256', 'ruled_sha256', 'tools', 'detail' }.
+        # status is 'in_force' only when every condition holds; otherwise tools
+        # is empty and status names the first condition that failed.
+        def load_effective(path: BASE_PATH, rulings: nil, rulings_error: nil)
+          rulings, rulings_error = chain_rulings if rulings.nil? && rulings_error.nil?
+          raw = begin
+            File.binread(path)
+          rescue StandardError => e
+            return empty('table_unreadable', nil, detail: "#{e.class}: #{e.message[0, 120]}")
+          end
+          sha = Digest::SHA256.hexdigest(raw)
+          return empty('chain_unreadable', sha, detail: rulings_error) if rulings_error
+
+          latest = Array(rulings).select { |r| r['table'] == TABLE_ID && r['attested'] == true }.last
+          return empty('no_ruling', sha) unless latest
+          return empty('withdrawn', sha, ruling: latest) if latest['action'] == 'withdraw'
+          return empty('invalid_ruling', sha, ruling: latest) unless latest['action'] == 'activate'
+          return empty('hash_mismatch', sha, ruling: latest) unless latest['sha256'] == sha
+
+          table, error = parse_table(raw)
+          return empty('invalid', sha, ruling: latest, detail: error) if error
+
+          table.merge('status' => 'in_force', 'sha256' => sha, 'ruled_sha256' => latest['sha256'],
+                      'ruled_at' => latest['ruled_at'])
+        end
+
+        def empty(status, sha, ruling: nil, detail: nil)
+          out = { 'status' => status, 'sha256' => sha, 'tools' => {}, 'write_roots' => [], 'write_extensions' => [],
+                  'write_name_prefix' => nil }
+          out['ruled_sha256'] = ruling['sha256'] if ruling
+          out['detail'] = detail if detail
+          out
+        end
+
+        # [table, nil] or [nil, error]. table: { 'tools' => { name => { 'effect',
+        # 'risk', 'locations' } }, 'write_roots' => [relative dirs],
+        # 'write_extensions' => ['.md', ...] }.
+        def parse_table(raw)
+          doc = YAML.safe_load(raw)
+          return [nil, 'not a mapping with a tools mapping'] unless doc.is_a?(Hash) && doc['tools'].is_a?(Hash)
+
+          forbidden = forbidden_patterns
+          tools = {}
+          doc['tools'].each do |name, row|
+            name = name.to_s
+            return [nil, "row #{name}: not a mapping"] unless row.is_a?(Hash)
+
+            effect = row['effect'].to_s
+            return [nil, "row #{name}: effect #{effect.inspect} is not admissible"] unless EFFECT_RISK.key?(effect)
+            if forbidden.any? { |pat| File.fnmatch(pat, name) }
+              return [nil, "row #{name}: refused by the act-route deny-lists"]
+            end
+
+            locations = row['locations'] || []
+            unless locations.is_a?(Array) && locations.all? { |l| l.is_a?(String) && !l.empty? }
+              return [nil, "row #{name}: locations must be a list of argument names"]
+            end
+
+            tools[name] = { 'effect' => effect, 'risk' => EFFECT_RISK[effect], 'locations' => locations }
+          end
+
+          roots = doc['write_roots'] || []
+          exts = doc['write_extensions'] || []
+          return [nil, 'write_roots must be a list of directories'] unless roots.is_a?(Array) && roots.all?(String)
+          return [nil, 'write_extensions must be a list such as .md'] unless exts.is_a?(Array) && exts.all?(String)
+
+          adm = ::KairosMcp::SkillSets::Agent::Admission
+          roots = roots.map { |r| r.strip.sub(%r{/+\z}, '') }
+          bad_root = roots.find do |r|
+            parts = r.split(%r{[/\\]})
+            r.empty? || r.match?(/[[:cntrl:]\\]/) || r.start_with?('/', '~') || parts.include?('..') ||
+              parts.include?('.') || parts.any?(&:empty?) ||
+              adm.protected_name?(r)
+          end
+          return [nil, "write_roots: #{bad_root.inspect} must be a relative directory inside the project"] if bad_root
+
+          exts = exts.map { |e| e.strip.downcase }
+          bad_ext = exts.find { |e| !e.match?(/\A\.[a-z0-9]+\z/) }
+          return [nil, "write_extensions: #{bad_ext.inspect} is not an extension such as .md"] if bad_ext
+
+          prefix = doc['write_name_prefix']
+          unless prefix.nil? || (prefix.is_a?(String) && prefix.match?(/\A[a-z0-9][a-z0-9_-]*\z/))
+            return [nil, "write_name_prefix: #{prefix.inspect} is not a plain prefix such as draft_"]
+          end
+
+          if tools.any? { |_, r| LIVE_TREE_EFFECTS.include?(r['effect']) } && (roots.empty? || exts.empty? || prefix.nil?)
+            return [nil, 'a reversible_local row needs write_roots, write_extensions and write_name_prefix']
+          end
+
+          [{ 'tools' => tools, 'write_roots' => roots, 'write_extensions' => exts,
+             'write_name_prefix' => prefix }, nil]
+        rescue Psych::Exception => e
+          [nil, "YAML: #{e.message[0, 120]}"]
+        end
+
+        # The step's tool row, or nil when the step is not classified for this
+        # act. A live-tree effect is classified only without the guard and only
+        # when write_scope (a callable from the driver, which knows the roots a
+        # tool resolves against) accepts the step; no write_scope, no write.
+        def row_for(step, effective, guard: false, write_scope: nil)
+          return nil unless step.is_a?(Hash)
+
+          row = effective['tools'][step['tool_name'].to_s]
+          return nil unless row
+          if LIVE_TREE_EFFECTS.include?(row['effect'])
+            return nil if guard || write_scope.nil? || !write_scope.call(step)
+          end
+
+          row
+        end
+
+        # The higher of the table's risk and the plan's own label: the label may
+        # raise a step's risk, never lower it. The label is the step's risk, or
+        # the plan's risk_default when the step names none; a label that is not
+        # one of low / medium / high (in any case) counts as high.
+        def resolved_risk(row, step_risk)
+          label = step_risk.to_s.downcase
+          own = RISK_ORDER.include?(label) ? label : 'high'
+          [row['risk'], own].max_by { |r| RISK_ORDER.index(r) }
+        end
+
+        # [copy, set_aside]. The copy marks every unclassified step for the
+        # operator and carries the resolved risk on classified ones. set_aside
+        # lists what the driver marked: [{ 'step_id', 'tool_name' }].
+        def apply(task_json, effective, guard: false, write_scope: nil)
+          copy = JSON.parse(JSON.generate(task_json || {}))
+          set_aside = []
+          default_risk = copy['meta'].is_a?(Hash) ? copy['meta']['risk_default'] : nil
+          Array(copy['steps']).each do |step|
+            next unless step.is_a?(Hash)
+
+            row = row_for(step, effective, guard: guard, write_scope: write_scope)
+            if row
+              step['risk'] = resolved_risk(row, step['risk'].nil? ? (default_risk || 'low') : step['risk'])
+            elsif step['requires_human_cognition'] != true
+              step['requires_human_cognition'] = true
+              set_aside << { 'step_id' => step['step_id'], 'tool_name' => step['tool_name'] }
+            end
+          end
+          [copy, set_aside]
+        end
+
+        # Values of the step's location arguments as the table names them. A
+        # step the table does not classify (or no table in force) falls back to
+        # the common names, so the signals do not go quiet without a ruling.
+        FALLBACK_LOCATIONS = %w[file_path path source destination].freeze
+
+        def location_values(step, effective)
+          row = effective && effective['tools'][step['tool_name'].to_s]
+          names = row ? row['locations'] : FALLBACK_LOCATIONS
+          args = step['tool_arguments'].is_a?(Hash) ? step['tool_arguments'] : {}
+          names.filter_map { |n| args[n].is_a?(String) ? args[n] : nil }
+        end
+
+        # ---- the terminal ruling (INV-D8) ----
+
+        NONCE_ALPHABET = %w[a c d e f h j k m n p r t u v w x y 3 4 7 9].freeze
+
+        def nonce
+          Array.new(6) { NONCE_ALPHABET[SecureRandom.random_number(NONCE_ALPHABET.size)] }.join
+        end
+
+        # Shows what is about to be ruled on tty_out, asks for the nonce on
+        # tty_in, and appends the ruling to the chain only when the typed nonce
+        # matches. action: 'activate' (the file's current bytes) or 'withdraw'.
+        # Returns { 'recorded' => bool, ... }.
+        def interactive_rule(action:, tty_in:, tty_out:, path: BASE_PATH, chain: nil, nonce_value: nonce)
+          raise ArgumentError, "action must be activate or withdraw, not #{action.inspect}" unless %w[activate withdraw].include?(action)
+
+          sha = nil
+          if action == 'activate'
+            # One read: the hash ruled on is the hash of the bytes shown.
+            raw = File.binread(path)
+            sha = Digest::SHA256.hexdigest(raw)
+            table, error = parse_table(raw)
+            if error
+              tty_out.puts "Refused: #{path} is not a valid table (#{error})."
+              return { 'recorded' => false, 'reason' => 'invalid', 'detail' => error }
+            end
+            tty_out.puts "Table:  #{TABLE_ID}"
+            tty_out.puts "File:   #{path}"
+            tty_out.puts "sha256: #{sha}"
+            tty_out.puts 'Tools the act route may run once this ruling is recorded:'
+            table['tools'].sort.each { |name, row| tty_out.puts "  #{name.ljust(18)} #{row['effect']}" }
+            tty_out.puts "Work-tree writes (reversible_local) only inside: #{table['write_roots'].join(', ')}"
+            tty_out.puts "  and only for files named #{table['write_name_prefix']}* ending in: #{table['write_extensions'].join(', ')}"
+            tty_out.puts '  (with the guard on, work-tree writes are set aside regardless)'
+          else
+            tty_out.puts "Withdraw table #{TABLE_ID}: the act route will run nothing until a new ruling."
+          end
+          tty_out.puts
+          tty_out.print "Type #{nonce_value} to record this ruling (anything else cancels): "
+          tty_out.flush
+          typed = tty_in.gets.to_s.strip
+          unless typed == nonce_value
+            tty_out.puts 'Cancelled. Nothing was recorded.'
+            return { 'recorded' => false, 'reason' => 'nonce_mismatch' }
+          end
+
+          record = { 'kind' => RULING_KIND, 'table' => TABLE_ID, 'action' => action, 'sha256' => sha,
+                     'attested' => true, 'attestation' => 'terminal_nonce',
+                     'ruled_at' => Time.now.utc.iso8601 }
+          chain ||= begin
+            require 'kairos_mcp/kairos_chain/chain'
+            ::KairosMcp::KairosChain::Chain.new
+          end
+          block = chain.add_block([JSON.generate(record)])
+          tty_out.puts "Recorded as block ##{block.index}."
+          { 'recorded' => true, 'block_index' => block.index, 'record' => record }
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/agent/lib/agent/act_classification.yml

@@ -0,0 +1,54 @@
+# Act-route classification — the agent's allow-list (design v0.3, INV-A1).
+#
+# A step runs on the act route only if its tool is listed here. Every other
+# step is set aside for the operator at the end of the cycle.
+#
+# This is the base table shipped with the gem. It lives beside the code, not
+# under config/, because upgrade never overwrites an operator's config/ file:
+# a shipped change here must reach the instance. It is in force only while the
+# latest attested operator ruling names the sha256 of its exact bytes, so an
+# upgrade that changes it leaves the act route empty until the operator rules
+# again, at a terminal:
+#
+#   ruby .kairos/skillsets/agent/bin/agent_rule.rb activate
+#
+# effect: read_only | session_record | llm_sandboxed | reversible_local
+#   reversible_local is a work-tree write. It runs only when every location
+#   the step names lands inside write_roots with one of write_extensions;
+#   any other write is set aside. Under the guard it is always set aside,
+#   because the confined route is not wired.
+# locations: the arguments that name the file a step reads or writes (the
+#   complexity signals read them; the protected-path check matches every
+#   location-like argument by name and does not depend on this list).
+#
+# write_roots / write_extensions / write_name_prefix: where work-tree writes
+# may land, relative to the project. Writes are allowed by place rather than
+# refused by place: naming every location a tool executes (git hooks, editor
+# add-ons, CI) did not close. Inside the place, a file must be named with the
+# prefix, carry one of the extensions, and sit under no hidden ('.') name,
+# because other agent tools load instruction files such as CLAUDE.local.md or
+# GEMINI.md from subdirectories, and none loads draft_*.
+write_roots:
+  - docs/drafts
+write_extensions: [.md, .txt]
+write_name_prefix: draft_
+
+tools:
+  resource_read:   { effect: read_only }
+  resource_list:   { effect: read_only }
+  knowledge_get:   { effect: read_only }
+  knowledge_list:  { effect: read_only }
+  skills_list:     { effect: read_only }
+  skills_get:      { effect: read_only }
+  document_status: { effect: read_only }
+  chain_status:    { effect: read_only }
+  chain_verify:    { effect: read_only }
+  chain_history:   { effect: read_only }
+  safe_file_read:  { effect: read_only, locations: [path] }
+  safe_file_list:  { effect: read_only, locations: [path] }
+  context_save:    { effect: session_record }
+  operator_report: { effect: session_record }
+  llm_call:        { effect: llm_sandboxed }
+  safe_file_write: { effect: reversible_local, locations: [path] }
+  safe_file_edit:  { effect: reversible_local, locations: [path] }
+  safe_file_copy:  { effect: reversible_local, locations: [source, destination] }