kairos-chain 3.88.2 → 3.89.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a785289fdb24dc921cad6c727b74168557a7dcf90593cb7ae267d2cb6b3501f
-  data.tar.gz: 422bb014ce8b479f765972b4f05fe57f86c71c09bae7c48277e8625b798767af
+  metadata.gz: 109c03e66d55828499533b9d00945390f97cfd8aa56376aa898c099a30218316
+  data.tar.gz: 3013372fe35ae2bf4e3e5a4267fed64197e7480da32f2030664eb61766724f44
 SHA512:
-  metadata.gz: b399c8a6e440d323ce30c73fb1c62acbb6fcefe7c67e76b89bed4171a3a9bc57d3af48de2ffb4cfc9ac4a802498dde65a868e0435564824d1f29a638748f3e73
-  data.tar.gz: 6b2fc4894c4d52489bb86580386a50121c64ebcdc7f1e363e18813f0a9a548d2a9f974104206fc66d4255b00119cb6f9d4c4b3b81523776a365c4b37be58779b
+  metadata.gz: 824d9d93d7e2c22a991e116a2f8c66acf8d54ecb2469a541c2f51a0ae982b0018d2650f88931daa5cf6da2091bba5ed470e13334c7b341d09fdfa2a7f48c01f8
+  data.tar.gz: bcc18d3c8123b54db6b934fc475f8517a7cd3dc2562a34d213c37140f08b45218d461c3685216f6577e9683de111f7ec70a07f9da27e5bfe947d0e740caffc5f

data/CHANGELOG.md

@@ -4,6 +4,53 @@ 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

data/lib/kairos_mcp/version.rb

@@ -1,4 +1,4 @@
 module KairosMcp
-  VERSION = "3.88.2"
+  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] }

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

@@ -62,8 +62,23 @@ module KairosMcp
         # .codex; .mcp.json) and the instruction files every agent body reads
         # (CLAUDE.md, AGENTS.md). Checked by destination, not by tool name, so
         # a tool that was not anticipated is covered by its arguments.
-        PROTECTED_SEGMENTS = %w[.kairos .claude .codex].freeze
-        PROTECTED_BASENAMES = %w[claude.md agents.md .mcp.json].freeze
+        #
+        # Also protected: what git and the operator's development tools execute
+        # or load as configuration (design v0.3 §6.5). A hook written into
+        # .git/hooks, or core.hooksPath set in .git/config, runs as the operator
+        # on the next git command, including a plain `git status` — which would
+        # hand the act the operator's shell. The same holds for CI workflows
+        # (.github), editor tasks (.vscode), other agents' rules (.cursor,
+        # .gemini, .cursorrules) and direnv (.envrc).
+        #
+        # And private keys: a keys/ directory anywhere, the usual private-key
+        # file names and extensions. The base table classifies safe_file_read,
+        # and a key read in one step could leave through an API llm_call in the
+        # next (keys/mmp_keypair.pem sits at this project's root).
+        PROTECTED_SEGMENTS = %w[.kairos .claude .codex .git .github .vscode .cursor .gemini keys].freeze
+        PROTECTED_BASENAMES = %w[claude.md agents.md .mcp.json .envrc .cursorrules .cursorignore
+                                 id_rsa id_dsa id_ecdsa id_ed25519].freeze
+        PROTECTED_EXTENSIONS = %w[.pem .key .p12 .pfx].freeze
 
         # Argument names that carry a filesystem location, matched by word
         # (split on '_' / '-') so 'profile' or 'output_format' is not a path.
@@ -146,7 +161,11 @@ module KairosMcp
             next [{ 'step_id' => step['step_id'], 'tool_name' => step['tool_name'], 'path' => '(no root)',
                     'rule' => 'unresolvable' }] if candidate_roots.empty? && !pairs.empty?
             pairs.filter_map do |_key, raw|
-              rule = if protected_name?(raw) then 'protected'
+              # A leading '~' is read as the home directory by File.expand_path
+              # but kept as a literal directory name by the tools (File.join), so
+              # the check and the write would disagree about where it lands.
+              rule = if raw.start_with?('~') then 'tilde'
+                     elsif protected_name?(raw) then 'protected'
                      elsif raw.split(%r{[/\\]}).include?('..') then 'dotdot'
                      else candidate_roots.lazy.map { |root| touch_rule(raw, root, protected, allowed) }.find(&:itself)
                      end
@@ -199,11 +218,83 @@ module KairosMcp
           end
         end
 
+        # True when a work-tree write is inside its allowed place (design v0.3
+        # §6.5 as ruled 2026-10-06). The accepted input is deliberately narrow,
+        # so that this check and the tool read the path the same way: every
+        # location argument must be a plain relative path, written as
+        # '<write root>/.../<name>', with no root argument beside it. Then:
+        #   - no segment below the root may start with '.' (no hidden files or
+        #     directories, where agent tools keep rules), as written and as
+        #     resolved;
+        #   - the file name must start with name_prefix and carry one of
+        #     extensions, as written and as resolved (no agent tool loads
+        #     'draft_*' as instructions; a link named .md is not a document);
+        #   - resolved with symlinks followed against every default root a tool
+        #     may use, the path must land strictly inside the same write root.
+        # A leading '/', '~' or '\', a backslash, an empty, '.' or '..' segment,
+        # a NUL or other control character, a root argument, or anything that
+        # cannot be resolved makes the step not inside. Never raises.
+        def within_write_scope?(args, write_roots, extensions, roots, project_root:, name_prefix: nil)
+          return false unless args.is_a?(Hash)
+
+          pairs = path_pairs(args)
+          root_args, files = pairs.partition { |k, _| (key_tokens(k) & ROOT_TOKENS).any? }
+          return false if files.empty? || !root_args.empty?
+
+          exts = Array(extensions).map(&:downcase)
+          candidates = Array(roots).compact.map(&:to_s).reject(&:empty?)
+          rels = Array(write_roots).map(&:to_s)
+          return false if rels.empty? || exts.empty? || candidates.empty?
+
+          name_ok = lambda do |name|
+            exts.include?(File.extname(name).downcase) && (name_prefix.nil? || name.start_with?(name_prefix))
+          end
+
+          files.all? do |_key, raw|
+            next false if raw.match?(/[[:cntrl:]\\]/) || raw.start_with?('/', '~')
+
+            segments = raw.split('/', -1)
+            next false if segments.any? { |p| p.empty? || p == '.' || p == '..' }
+
+            rel = rels.find { |r| raw.start_with?("#{r}/") }
+            next false unless rel
+
+            below = raw.delete_prefix("#{rel}/").split('/')
+            next false if below.empty? || below.any? { |p| p.start_with?('.') } || !name_ok.call(below.last)
+
+            dir = canonical(File.expand_path(rel, project_root))
+            candidates.all? do |root|
+              full = canonical(File.expand_path(raw, root))
+              next false unless full.start_with?("#{dir}/")
+
+              resolved = full.delete_prefix("#{dir}/").split('/')
+              !resolved.empty? && resolved.none? { |p| p.start_with?('.') } && name_ok.call(resolved.last)
+            rescue StandardError
+              false
+            end
+          rescue StandardError
+            false
+          end
+        rescue StandardError
+          false
+        end
+
         # A protected segment or file name anywhere in the path refuses it,
         # whatever root the tool resolves against.
         def protected_name?(raw)
+          # A control character (NUL included) is refused outright: no real
+          # location needs one, and File.extname raises on NUL.
+          return true if raw.to_s.match?(/[[:cntrl:]]/)
+
           parts = raw.split(%r{[/\\]}).map(&:downcase)
-          parts.any? { |p| PROTECTED_SEGMENTS.include?(p) } || PROTECTED_BASENAMES.include?(parts.last)
+          # No hidden name, anywhere, for any step (operator ruling 2026-10-06):
+          # dotfiles and dot-directories are where secrets (.env, .ssh, .aws,
+          # .netrc) and tool configuration live, and naming them one by one did
+          # not close. '.' and '..' are not names; '..' is refused on its own.
+          return true if parts.any? { |p| p.start_with?('.') && p != '.' && p != '..' }
+
+          parts.any? { |p| PROTECTED_SEGMENTS.include?(p) } || PROTECTED_BASENAMES.include?(parts.last) ||
+            PROTECTED_EXTENSIONS.include?(File.extname(parts.last.to_s))
         end
 
         # True when the path, resolved against root, lands in a protected