kairos-chain 3.88.2 → 3.90.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a785289fdb24dc921cad6c727b74168557a7dcf90593cb7ae267d2cb6b3501f
-  data.tar.gz: 422bb014ce8b479f765972b4f05fe57f86c71c09bae7c48277e8625b798767af
+  metadata.gz: b1f38307df012164fc2070ff3a5a7489f651c678e4bcb75f4d93ef2ba65dec6d
+  data.tar.gz: 11f40f3abe1a502600d451ffb4e6fe757f1cd351fa7f9af7c4c09fe0669f776c
 SHA512:
-  metadata.gz: b399c8a6e440d323ce30c73fb1c62acbb6fcefe7c67e76b89bed4171a3a9bc57d3af48de2ffb4cfc9ac4a802498dde65a868e0435564824d1f29a638748f3e73
-  data.tar.gz: 6b2fc4894c4d52489bb86580386a50121c64ebcdc7f1e363e18813f0a9a548d2a9f974104206fc66d4255b00119cb6f9d4c4b3b81523776a365c4b37be58779b
+  metadata.gz: 5886c559503ae2223da85857a13e8fa2b365271f5988c3a24b77675ce56215ca481fb581d60f82f523dfe9a1cce4fb81e8b5cfc70f81fb68beec4142183c4450
+  data.tar.gz: de3e9624a91ef9bbc9eaf3712cf64e6367f8b13523c1f3ace774cd31d0c7be4aa5560d60d7f8bfda9197802165dea0ab8a5dd7c74cb2bf666f4c903b26603249

data/CHANGELOG.md

@@ -4,6 +4,95 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.90.0] - 2026-10-07
+
+### Added — agent: every answer is a ruling on the chain, and an answer typed at a terminal binds
+
+Until now the gate log kept which answer advanced a session, but not who gave
+it, why, or what it was given to. **Every answer that advances an agent session
+is now recorded on the chain as a ruling** (`agent_answer`) — through
+`agent_step` (approve, revise, skip, stop, adjudicate) and `agent_stop` alike.
+
+- **What a ruling holds**: the point it answered (state, cycle, and why the
+  session was waiting), the plan's SHA-256 and the driver's own signals when a
+  plan was the subject, the act-route table in force, the decision, and whether
+  it was attested. A replayed retry writes none. A ruling that fails to record
+  never blocks the answer; the response says so under `ruling`. Reasons
+  (`rationale`, new optional argument) and revise feedback stay off the chain;
+  the ruling carries their SHA-256.
+- **Answer as yourself, at a terminal**:
+
+      ruby .kairos/skillsets/agent/bin/agent_rule.rb answer SESSION_ID
+
+  It shows why the session stopped and the whole plan (every argument, escaped,
+  and the file it is kept in), asks for your answer, an optional reason and a
+  nonce, and records the answer bound to that point and that plan. The answer
+  then sent through `agent_step` there must be the same one, or it is refused
+  (`answer_refused`); **a stop always goes through**. After a revise at the
+  terminal, send `revise` without feedback and your text is used. Pass
+  `--project-dir` when the MCP server runs in another directory than the
+  project holding its data dir. An answer sent only through MCP is recorded as
+  the caller's, unattested.
+- **Every waiting session says why it stopped** (`stop` in every response and in
+  `agent_status`). `cycle_checkpoint` means only the scheduled end-of-cycle
+  stop (Gate 8, or a manual act that succeeded and left nothing over); failed
+  acts, set-aside steps, guard halts, adjudications, risk pauses and the rest
+  name themselves.
+- **While the chain cannot be read, every answer but a stop is refused**,
+  because whether you answered at the terminal cannot be checked. On chain
+  stores other than the file ledger (sqlite, postgresql) the agent can only be
+  stopped.
+
+No action is needed after upgrading. Approval delegation (the shadow judge) is
+not part of this release; do not run the agent unattended.
+
+## [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

data/lib/kairos_mcp/version.rb

@@ -1,4 +1,4 @@
 module KairosMcp
-  VERSION = "3.88.2"
+  VERSION = "3.90.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,106 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# The operator's terminal rulings for the agent (design v0.3, INV-A2 / INV-D8):
+# the act-route allow-list, and answers at a stopped session.
+#
+#   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)
+#   ruby .kairos/skillsets/agent/bin/agent_rule.rb answer SESSION_ID
+#                         # answer a stopped session; the MCP answer there must then match
+#
+# Options: --data-dir DIR     the instance data dir whose chain is written
+#                             (default: the .kairos this script is installed in)
+#          --project-dir DIR  answer only: the directory the MCP server runs in,
+#                             whose .kairos/storage holds its agent sessions
+#                             (default: the directory holding the data dir).
+#                             Needed when the server runs with --data-dir
+#                             pointing at another project's .kairos.
+#
+# activate, withdraw and answer 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 answer].include?(a) }
+abort 'usage: agent_rule.rb activate|withdraw|status|answer SESSION_ID [--data-dir DIR]' unless action
+session_id = action == 'answer' ? ARGV[ARGV.index('answer') + 1].to_s : nil
+abort 'usage: agent_rule.rb answer SESSION_ID [--data-dir DIR]' if session_id&.then { |s| s.empty? || s.start_with?('-') }
+
+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 == 'answer'
+  require 'kairos_mcp/invocation_context'
+  require File.join(lib, 'agent', 'session')
+  require File.join(lib, 'agent', 'advance_gate')
+  require File.join(lib, 'agent', 'answer_ruling')
+  # The server keeps agent sessions under <its working directory>/.kairos/storage
+  # (Session.storage_path without Autonomos loaded), and its chain under its
+  # data dir. The two can differ; the answer is read from the first and
+  # recorded on the second, the chain the server reads.
+  pidx = ARGV.index('--project-dir')
+  abort 'usage: agent_rule.rb answer SESSION_ID --project-dir DIR' if pidx && ARGV[pidx + 1].to_s.then { |v| v.empty? || v.start_with?('-') }
+  project_dir = pidx ? File.expand_path(ARGV[pidx + 1].to_s) : File.dirname(data_dir)
+  abort "no project dir at #{project_dir}" unless File.directory?(project_dir)
+  Dir.chdir(project_dir)
+  session = KairosMcp::SkillSets::Agent::Session.load(session_id)
+  unless session
+    abort "no agent session #{session_id} under #{File.join(Dir.pwd, '.kairos', 'storage', 'agent_sessions')} " \
+          '(if the MCP server runs in another directory, pass --project-dir)'
+  end
+  puts "Sessions from: #{project_dir}"
+end
+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 = if action == 'answer'
+             KairosMcp::SkillSets::Agent::AnswerRuling.interactive_answer(
+               session: session, gate: KairosMcp::SkillSets::Agent::AdvanceGate.new(session.guard_dir),
+               tty_in: tty, tty_out: tty, reload: -> { KairosMcp::SkillSets::Agent::Session.load(session_id) }
+             )
+           else
+             ac.interactive_rule(action: action, tty_in: tty, tty_out: tty, path: path)
+           end
+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] }