kairos-chain 3.64.0 → 3.65.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ba66e678675e9b4e7776676832765d509f0ac7bb49feed159ee1513ba4b7318
-  data.tar.gz: 28af1484af3a0c98529603bfa30fd9ff188e5b18895c06c11a313bcf3a95d8b2
+  metadata.gz: 0b5f8504e1a59fe2e58603f654ad32a747381897a62dba70ba436388c5be3f55
+  data.tar.gz: c4c86ca90fb56858a45c126aca497277846225c1b127549700be1e80484c0755
 SHA512:
-  metadata.gz: 67e98820708350d674970e3db49f3583efc01491ba8d58f5ecb702b988f64a5ad1efeb083637f45e77897c44dbb30a84569400431e8f669020fb13a2dae7b4aa
-  data.tar.gz: 27fef53ab90cdb4a7745955b49d41e3834d8313f0a0417605a96e21e84b0ab44fcb5c0e3ad27d9ff2cf698bda2a75c0dc7712869ab5e686daeb8cc468da77cdf
+  metadata.gz: 3535630f908f30fc87319e960207ea5552de1f29284211cf24e4802171a7699b3ebcde4ebce74875341d368004ea04ccf36211f4b68037755907a1ef77550ae6
+  data.tar.gz: a01fbf7861eac890a2d020ce8a0606970d41a7a9f3d0f1840f1db7a19580c87f77b77af1ffebd4028c538f4535b562db78adff1c847389c2fd6a162dda5fa3f4

data/CHANGELOG.md

@@ -4,6 +4,52 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.65.0] - 2026-08-13
+
+### Changed
+
+- **Ruby 3.2 is now the minimum.** The `readable_gate` Stop hook bounds its
+  scan with `Regexp.timeout`, which arrived in Ruby 3.2. Under the previous
+  floor of 3.0 that call raised, the gate's outermost rescue converted it to
+  exit 0, and the hook enforced nothing while reporting nothing. Guarding the
+  call was the alternative and is worse: without `Regexp.timeout` there is no
+  per-match bound either, so a declaration carrying many patterns could
+  consume the hook's whole budget and stall a turn. An install that fails is
+  louder than a gate that does not measure. Ruby 3.0 left security support in
+  April 2024 and 3.1 in March 2025.
+
+### Added
+
+- **`kairos_hook_projector` reaches stage 2.** The SkillSet gains two tools
+  that write the harness configuration — `mode_hooks_project`, which installs
+  a mode's declared hooks into `.claude/settings.json` behind a proposal and
+  a confirmation hash, and `mode_hooks_validate` — and two executables land on
+  PATH, `kairos-readable-gate` and `kairos-plugin-project`. Before this
+  release the SkillSet was read-only. `kairos-chain-daemon` also joins the
+  executable list; it shipped in the package but was never put on PATH.
+- **`kairos_hook_projector` gains a diagram floor.** A mode may declare
+  `diagram_required_over_lines`, and a message whose prose exceeds it while
+  carrying no fenced block is reported. It is the first floor among the
+  gate's thresholds, which are otherwise all caps, and the length
+  announcement deliberately does not clear it. Off unless a mode names a
+  number; the core supplies no threshold of its own.
+
+### Fixed
+
+- The gate no longer supplies a rewrite instruction of its own. The block
+  reason is addressed under the mode's name, so core-authored prose arrived
+  as something the mode had said. A mode that declares none now gets none.
+- A `.claude/settings.json` shape the projector cannot merge is refused rather
+  than silently discarded.
+- The measurement deadline reaches inside a single pattern's matches and into
+  the specimen scan, not only the loop between patterns.
+- A log rotation that cannot be performed no longer costs the record it was
+  making room for.
+- The gate exits 0 when `--config` is absent, as its documented invariant
+  always claimed; it exited 2, which a Stop hook reads as blocking.
+- `LICENSE` now exists under the gem build root. It was listed in
+  `spec.files` and absent from the published package.
+
 ## [3.64.0] - 2026-08-06
 
 ### Fixed

data/LICENSE

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

data/README.md

@@ -1,7 +1,7 @@
 # KairosChain MCP Server
 
 [![Gem Version](https://img.shields.io/gem/v/kairos-chain)](https://rubygems.org/gems/kairos-chain)
-[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0-red)](https://www.ruby-lang.org/)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-red)](https://www.ruby-lang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 A self-referential [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for auditable skill self-management. KairosChain enables AI agents to define, evolve, and audit their own capabilities through a three-layer knowledge system backed by a private blockchain.
@@ -108,7 +108,32 @@ kairos-chain -v                    # Show version
 
 KairosChain's architecture flows from one principle: **meta-level operations are expressed in the same structure as base-level operations.** This structural self-referentiality enables agents to reason about, modify, and evolve their own capabilities using the same tools they use for base-level tasks.
 
-See [CLAUDE.md](../CLAUDE.md) for the full philosophical framework including the Nine Propositions.
+### Why "Pure" Skills
+
+The name is borrowed from *pure functions* — functions whose output depends only on their declared
+arguments, and which change nothing outside their return value. A capability written in prose is
+impure in two ways. Its behaviour depends on things the definition does not declare: the rest of the
+context window, the model version, whatever else happens to be loaded. And what it actually did
+cannot be checked from the definition, either before the run or after it.
+
+Purity here does not mean the absence of effects. Agents do write files and reach out to the world.
+It means that **where the impurity lives is declared in the definition itself.** Inside a
+`definition` block, `constraint` and `check` carry the machine-decidable part, while the fifth
+constructor, `node`, marks the part a machine cannot decide. The evaluation engine returns those
+nodes as non-evaluable and leaves satisfaction as `:unknown` rather than true or false:
+
+```ruby
+# SemanticReasoning — explicitly non-evaluable (requires human judgment)
+satisfied: :unknown,
+evaluable: false
+```
+
+Like a type system that surfaces effects instead of removing them, the undecidable part is recorded
+as undecidable rather than hidden. How much of a capability has been formalised therefore becomes
+machine-readable — which is what `dsl_ast/drift_detector.rb` measures.
+
+See [CLAUDE.md](../CLAUDE.md) for the full philosophical framework including the Nine Propositions,
+and the `kairoschain_design` L1 knowledge entry for the Pure Skills directory structure.
 
 ## Author
 

data/bin/kairos-readable-gate

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Harness-side entry point for the readable-output gate.
+#
+# Usage (as a Claude Code Stop hook, produced by mode_hooks_project):
+#   kairos-readable-gate --config <path/to/gate_config.json>
+#
+# Why this entry point exists rather than the hook naming the gate directly:
+#
+#   1. PluginProjector only projects hook commands matching /\Akairos-/ without
+#      warning. A raw path command warns on every projection, and a warning
+#      nobody can act on trains operators to ignore warnings.
+#   2. The gate's location differs between an installed SkillSet and the gem's
+#      own templates. Resolving it here keeps that off the compiled artifact,
+#      which must stay a pure function of (mode identity, declaration).
+#
+# It used to carry a third job — finding a python3 — which went away with the
+# port to Ruby on 2026-08-12. The gate now runs in this process rather than a
+# spawned one, so a turn pays one interpreter start instead of two.
+#
+# stdin, stdout and the exit status are passed through untouched: this entry
+# point must never turn a gate verdict into something else. If the gate cannot
+# be found or cannot be run, it exits 0 and emits nothing — a broken gate must
+# not wedge a session.
+
+SCRIPT_REL = File.join('skillsets', 'kairos_hook_projector', 'hooks', 'readable_gate.rb')
+
+def candidate_scripts
+  paths = []
+  paths << ENV['KAIROS_READABLE_GATE_SCRIPT'] if ENV['KAIROS_READABLE_GATE_SCRIPT']
+
+  # Installed SkillSet, under the instance data dir.
+  data_dir = ENV['KAIROS_DATA_DIR']
+  data_dir ||= File.join(Dir.pwd, '.kairos')
+  paths << File.join(data_dir, SCRIPT_REL)
+
+  # The gem's own templates, for an instance that has not acquired the SkillSet.
+  gem_root = File.expand_path('..', __dir__)
+  paths << File.join(gem_root, 'templates', SCRIPT_REL)
+
+  paths
+end
+
+script = candidate_scripts.find { |p| p && File.file?(p) }
+
+if script.nil?
+  warn '[kairos-readable-gate] not run: gate script not found'
+  exit 0
+end
+
+code = begin
+  require script
+  KairosHookProjector::ReadableGate.main
+rescue StandardError, SystemStackError, LoadError => e
+  warn "[kairos-readable-gate] not run: #{e.class}: #{e.message}"
+  0
+end
+
+exit code

data/lib/kairos_mcp/admin/helpers.rb

@@ -3,6 +3,7 @@
 require 'erb'
 require 'securerandom'
 require 'digest'
+require_relative '../path_containment'
 
 module KairosMcp
   module Admin
@@ -88,8 +89,13 @@ module KairosMcp
       # @param filename [String] File name in static/ directory
       # @return [Array] Rack response triple
       def serve_static(filename)
+        # filename comes straight from PATH_INFO on the one admin route that
+        # requires no authentication, so containment is what stands between an
+        # anonymous request and any file this process can read.
         filepath = File.join(STATIC_DIR, filename)
-        return [404, {}, ['Not found']] unless File.exist?(filepath)
+        unless PathContainment.contained?(STATIC_DIR, filepath) && File.file?(filepath)
+          return [404, {}, ['Not found']]
+        end
 
         content_type = case File.extname(filename)
                        when '.css' then 'text/css'

data/lib/kairos_mcp/anthropic_skill_parser.rb

@@ -3,6 +3,7 @@
 require 'yaml'
 require 'fileutils'
 require 'securerandom'
+require_relative 'path_containment'
 
 module KairosMcp
   # AnthropicSkillParser: Parses Anthropic skills format (YAML frontmatter + Markdown)
@@ -150,7 +151,7 @@ module KairosMcp
       def list_scripts(skill)
         return [] unless skill.has_scripts?
 
-        Dir[File.join(skill.scripts_path, '*')].map do |f|
+        Dir[File.join(skill.scripts_path, '*')].select { |f| inside_entry?(skill.base_path, f) }.map do |f|
           {
             name: File.basename(f),
             path: f,
@@ -167,7 +168,7 @@ module KairosMcp
       def list_assets(skill)
         return [] unless skill.has_assets?
 
-        Dir[File.join(skill.assets_path, '**/*')].select { |f| File.file?(f) }.map do |f|
+        Dir[File.join(skill.assets_path, '**/*')].select { |f| File.file?(f) && inside_entry?(skill.base_path, f) }.map do |f|
           {
             name: File.basename(f),
             path: f,
@@ -185,7 +186,7 @@ module KairosMcp
       def list_references(skill)
         return [] unless skill.has_references?
 
-        Dir[File.join(skill.references_path, '**/*')].select { |f| File.file?(f) }.map do |f|
+        Dir[File.join(skill.references_path, '**/*')].select { |f| File.file?(f) && inside_entry?(skill.base_path, f) }.map do |f|
           {
             name: File.basename(f),
             path: f,
@@ -230,14 +231,27 @@ module KairosMcp
         end
       end
 
+      # An entry's markdown file lives inside that entry's directory. That is
+      # true by the definition of the format, so it is enforced here rather
+      # than left to each of the callers to remember.
+      #
+      # Both branches need it. The named branch can be a symlink pointing out
+      # of the entry, and the glob branch returns whatever the glob happened to
+      # find, which can be the same. Without this, reading an entry returned
+      # content from wherever the link led — ResourceRegistry defends its own
+      # read against exactly this, and the parser did not.
       def find_md_file(skill_dir)
         # First try to find a file with the same name as the directory
         skill_name = File.basename(skill_dir)
         expected_file = File.join(skill_dir, "#{skill_name}.md")
-        return expected_file if File.exist?(expected_file)
+        return expected_file if File.exist?(expected_file) && inside_entry?(skill_dir, expected_file)
 
         # Fall back to any .md file in the directory
-        Dir[File.join(skill_dir, '*.md')].first
+        Dir[File.join(skill_dir, '*.md')].find { |f| inside_entry?(skill_dir, f) }
+      end
+
+      def inside_entry?(skill_dir, path)
+        PathContainment.contained?(skill_dir, path)
       end
     end
   end

data/lib/kairos_mcp/context_manager.rb

@@ -4,6 +4,7 @@ require 'fileutils'
 require 'yaml'
 require_relative 'anthropic_skill_parser'
 require_relative 'context_graph'
+require_relative 'path_containment'
 require_relative '../kairos_mcp'
 
 module KairosMcp
@@ -43,7 +44,10 @@ module KairosMcp
     # @param session_id [String] Session ID
     # @return [Array<Hash>] List of context summaries
     def list_contexts_in_session(session_id)
+      return [] unless segments?(session_id)
+
       session_dir = File.join(@context_dir, session_id)
+      return [] unless contained?(session_dir)
       return [] unless File.directory?(session_dir)
 
       context_dirs(session_dir).map do |dir|
@@ -66,7 +70,10 @@ module KairosMcp
     # @param name [String] Context name
     # @return [AnthropicSkillParser::SkillEntry, nil] The context entry or nil
     def get_context(session_id, name)
+      return nil unless segments?(session_id, name)
+
       context_dir = File.join(@context_dir, session_id, name)
+      return nil unless contained?(context_dir)
       return nil unless File.directory?(context_dir)
 
       AnthropicSkillParser.parse(context_dir)
@@ -83,10 +90,18 @@ module KairosMcp
       validate_relations_in_content!(content)
 
       session_dir = File.join(@context_dir, session_id)
-      FileUtils.mkdir_p(session_dir)
-
       context_dir = File.join(session_dir, name)
 
+      # Checked before mkdir_p, so neither value can create a directory outside
+      # the store. Both guards are needed: containment bounds the composed leaf,
+      # and the segment check bounds session_dir and the second join the parser
+      # performs on `name` — paths this method never composes itself.
+      unless segments?(session_id, name) && contained?(context_dir)
+        return { success: false, error: "Invalid session_id/name: '#{session_id}/#{name}' resolves outside the context directory" }
+      end
+
+      FileUtils.mkdir_p(session_dir)
+
       if File.directory?(context_dir)
         # Update existing
         skill = AnthropicSkillParser.update(context_dir, content)
@@ -140,8 +155,10 @@ module KairosMcp
     # @return [Hash] Result with success status
     def delete_context(session_id, name)
       context_dir = File.join(@context_dir, session_id, name)
-      
-      unless File.directory?(context_dir)
+
+      # rm_rf below: containment is checked first so a traversing name cannot
+      # delete a tree outside the context store.
+      unless segments?(session_id, name) && contained?(context_dir) && File.directory?(context_dir)
         return { success: false, error: "Context '#{name}' not found in session '#{session_id}'" }
       end
 
@@ -155,8 +172,8 @@ module KairosMcp
     # @return [Hash] Result with success status
     def delete_session(session_id)
       session_dir = File.join(@context_dir, session_id)
-      
-      unless File.directory?(session_dir)
+
+      unless segments?(session_id) && contained?(session_dir) && File.directory?(session_dir)
         return { success: false, error: "Session '#{session_id}' not found" }
       end
 
@@ -178,13 +195,21 @@ module KairosMcp
       end
 
       context_dir = File.join(@context_dir, session_id, name)
-      unless File.directory?(context_dir)
+      unless segments?(session_id, name) && contained?(context_dir) && File.directory?(context_dir)
         return { success: false, error: "Context '#{name}' not found in session '#{session_id}'" }
       end
 
       subdir_path = File.join(context_dir, subdir)
+      unless contained?(subdir_path)
+        return { success: false, error: "Invalid subdir '#{subdir}': resolves outside the context directory" }
+      end
+
+      # mkdir_p raises Errno::EEXIST when the name is taken by a dangling
+      # symlink, and this method's contract is a result hash, not an exception.
       FileUtils.mkdir_p(subdir_path)
       { success: true, path: subdir_path }
+    rescue SystemCallError => e
+      { success: false, error: "Could not create subdir '#{subdir}': #{e.message}" }
     end
 
     # Generate a unique session ID
@@ -223,12 +248,29 @@ module KairosMcp
 
     private
 
+    # True if a path built from a caller-supplied session_id / name still
+    # resolves inside the context store.
+    def contained?(path)
+      PathContainment.contained?(@context_dir, path)
+    end
+
+    # True if every caller-supplied value names one directory.
+    #
+    # Containment alone is not enough here: "." and ".." resolve back onto the
+    # store root, which is inside it, so a delete addressed that way would take
+    # the whole store. A session id and a context name are always one level.
+    def segments?(*values)
+      values.all? { |v| PathContainment.safe_segment?(v) }
+    end
+
     def session_dirs
       Dir[File.join(@context_dir, '*')].select { |f| File.directory?(f) }
     end
 
+    # Listing follows Dir entries, so a child that is a symlink out of the store
+    # would otherwise be enumerated and parsed as if it were a context.
     def context_dirs(session_dir)
-      Dir[File.join(session_dir, '*')].select { |f| File.directory?(f) }
+      Dir[File.join(session_dir, '*')].select { |f| File.directory?(f) && contained?(f) }
     end
   end
 end