kairos-chain 3.31.0 → 3.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 227d024f36839c595295ed0e3b4415c6764750597283b59a21ea1f5e16112210
-  data.tar.gz: 8fd8767580dbe3db617cbaf4ee0dcfafdb38f5823315f0321bae0c4893b2f45d
+  metadata.gz: a393cfbac08011bdd6f7b8cd3129177f535c7507868215d6b85ef2af732e8521
+  data.tar.gz: 202af122d66197111412f5cdfc48287872713781602fe7f5f428ec40f3e111a9
 SHA512:
-  metadata.gz: 7486fef959f54577c0a13a301112f746f8c440100f11f5d424f27771759ad3024d6d30988b7a9e7c58a4544db1ffe6c2705b3271226d9445f1537dc591f96ef7
-  data.tar.gz: 8d670bb2a2f5d8d848072101527fcb5b3153c23ea4c5ae1359c1d46c30187011911b32512086e1e1734e72ba5d0d3ae20913499d5d1d8c4b4d1d359b79963281
+  metadata.gz: 880c1f5206e0e84ab3b448abd25e5ec3a2fd012840a0f0f2b1d67bd8883fc54da27a945e451de3c2dfc96c36628658db625190b8a8ad8dd8796b1c5b7cbf2eb1
+  data.tar.gz: 4a2187976ddddc4e4a27ef51075f38ddeff13539f60c8928150bce1d3d97d607b6bb09aa327179569209ddcf440cae575b53b1460e5f9f350553d2760a6e4a7a

data/CHANGELOG.md

@@ -4,6 +4,83 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.34.0] - 2026-07-03
+
+### Added — L1 knowledge (dev repo): loop_validation
+
+New L1 knowledge entry `loop_validation` (v0.4), the mechanical loop-verdict
+methodology distilled from the Autonomous Growth Loop governance design
+(FROZEN v0.3.1, 3-round multi-LLM review) and its slice-1 implementation.
+Body-agnostic reference engine (`scripts/kairos_verdict.py`, fail-closed, no
+LLM), example spec, and an instance-local hermes body adapter appendix.
+Realizes candidate A of the loop-engineering keystone analysis. Frozen at
+v0.4 after 3 multi-LLM review rounds (6/6 unanimous R3); R1 caught a real
+engine crash on malformed specs (execution-verified), R2 caught a wrapper
+constant-key breach and a reason-taxonomy desync.
+
+Scoped to `knowledge/` (dev repo) only this release — NOT promoted to
+`templates/` (user distribution) because the hermes adapter appendix carries
+instance-local absolute paths. Promotion to `templates/` awaits proven use
+and path placeholder-izing.
+
+### Design (docs, not gem): Autonomous Growth Loop governance v0.3.1 FROZEN
+
+10 governance invariants for an unattended growth loop (evidence-grounded
+fail-closed verdict, dual stop floor, norm-change asymmetry, human-authored
+run mandate grounded at the human per Prop 9, execution-events-as-attestation
+vs Meta-Ledger-for-capability-changes). Design artifact under `docs/drafts/`.
+
+## [3.33.0] - 2026-07-03
+
+### Added — L1 knowledge: loop_engineering_patterns
+
+New gem-bundled L1 knowledge entry `loop_engineering_patterns` (v0.3), sibling
+of `skill_authoring_patterns` (same distill-an-Anthropic-post-through-layers
+method). Distills Claude Code's "Getting Started with Loops" into: §A four loop
+types (two axes: trigger × human presence), §B universal loop-design craft,
+§C KairosChain layer placement (harness vs gem/SkillSet) plus the cross-cutting
+Prop 10 procedural-floor reading that the source omits. Source text is not
+redistributed; a facts-only provenance pointer lives in `references/`.
+
+- Shipped to both `knowledge/` and `templates/knowledge/` (mirrors sibling).
+- `skill_authoring_patterns` Related gains a reciprocal sibling link.
+- Frozen after 2 multi-LLM review rounds (6-reviewer roster, delegate strategy).
+  R1 caught one genuine (a) factual error (`confidence_exit_threshold` wrongly
+  described as unwired — it is wired at agent_step.rb Gate 7) and one overstated
+  mechanism status; R2 narrowed to wording-precision findings, resolved in v0.3.
+
+## [3.32.0] - 2026-07-03
+
+### Added — multi-host SkillSet projection (Codex + OpenCode)
+
+`PluginProjector` gains a `HostProfile` abstraction so projection targets Codex
+CLI and OpenCode in addition to Claude Code. Claude behavior is unchanged
+(byte-compatible; `projection_manifest.json` keeps its legacy name).
+
+- Instruction mode: `AGENTS.md` with the mode body inlined for codex/opencode
+  (they do not resolve Claude's `@`-import); `CLAUDE.md` `@`-import for claude.
+- Codex: `.codex/skills`, `.codex/agents`, `.codex/hooks.json` (merge-preserving
+  user hooks via `_projected_by` tags; re-projection hook commands carry
+  `--host codex`). Codex reads `<repo>/.codex/hooks.json` natively — no TOML.
+- OpenCode: reuses `.claude/skills/` (Claude co-use assumption), converts agents
+  to `.opencode/agent/` frontmatter; hooks skipped (OpenCode hooks are JS plugins).
+- CLI `kairos-chain mode` and `kairos-plugin-project` gain
+  `--host claude|codex|opencode`; MCP tool `plugin_project` gains a `host` param.
+  Per-host manifest slots so hosts coexist.
+- Hardened via multi-LLM implementation review (codex/claude/cursor, all
+  APPROVE-WITH-CHANGES, 0 P0): hooks merge-preserve, agent-conversion Hash guard
+  and list-form `disallowedTools`, separator-boundary path containment, live-file
+  region status, malformed `.codex/hooks.json` normalization. 111 projector tests.
+
+### Added — codex mcp-server reviewer backend (opt-in)
+
+`CodexMcpAdapter` drives Codex via `codex mcp-server` (stdio JSON-RPC, one-shot,
+read-only sandbox) as an alternative to the `codex exec` CLI adapter. A codex
+reviewer opts in with `backend: mcp` (default stays CLI, backward compatible);
+the backend switch is wired through `llm_call`, `call_router`, and the
+multi_llm_review dispatcher. A/B against the CLI path showed parity (same
+verdict, comparable latency).
+
 ## [3.31.0] - 2026-06-11
 
 ### Changed — multi_llm_review roster: Fable 5 + Opus 4.6/4.8 (6 reviewers)

data/bin/kairos-chain

@@ -376,6 +376,11 @@ when 'mode'
                              KAIROS_PROJECT_ROOT env, then cwd if it contains a
                              recognizable project marker (CLAUDE.md, .git/,
                              .claude/, or prior projection manifest).
+        --host HOST          Target host: claude (default) | codex | opencode.
+                             claude writes CLAUDE.md with an @-import pointer;
+                             codex/opencode write AGENTS.md with the mode body
+                             inlined (they do not resolve @-import). Each host
+                             uses a separate manifest slot, so hosts can coexist.
 
       Notes:
         - data_dir and consumer project root are decoupled (design v0.2,
@@ -410,6 +415,19 @@ when 'mode'
     ARGV.delete_at(idx)
   end
 
+  # 2026-07-02: target host for projection (claude | codex | opencode). Default claude.
+  # codex/opencode write AGENTS.md with the mode body inlined (they do not resolve @-import).
+  mode_host = 'claude'
+  if (idx = ARGV.index('--host'))
+    mode_host = ARGV[idx + 1]
+    if mode_host.nil? || mode_host.start_with?('--')
+      warn "ERROR: --host requires a value (claude, codex, or opencode)."
+      exit 1
+    end
+    ARGV.delete_at(idx + 1)
+    ARGV.delete_at(idx)
+  end
+
   require 'kairos_mcp/skills_config'
   require 'kairos_mcp/plugin_projector'
 
@@ -426,11 +444,15 @@ when 'mode'
 
   projector_mode = KairosMcp.projection_mode
   begin
-    projector = KairosMcp::PluginProjector.new(project_root, mode: projector_mode, data_dir: KairosMcp.data_dir)
+    projector = KairosMcp::PluginProjector.new(project_root, mode: projector_mode, data_dir: KairosMcp.data_dir, host: mode_host)
   rescue KairosMcp::PluginProjector::CoincidenceRefused => e
     warn "ERROR: #{e.message}"
     warn "  Use --project-root <path> to designate a directory distinct from the data directory."
     exit 1
+  rescue ArgumentError => e
+    warn "ERROR: #{e.message}"
+    warn "  Valid --host values: claude, codex, opencode."
+    exit 1
   end
 
   case mode_action
@@ -464,27 +486,31 @@ when 'mode'
       exit 1
     end
 
+    ctx_file = projector.host.context_file
     puts "Instruction mode projected:"
     puts "  mode             : #{instructions_mode}#{version ? " v#{version}" : ''}"
+    puts "  host             : #{projector.host.key} (delivery: #{projector.host.instruction_mode_delivery})"
     puts "  body source      : #{body_path}"
     puts "  project root     : #{project_root} (source: #{KairosMcp.consumer_project_root_source})"
     puts "  data dir         : #{KairosMcp.data_dir}"
     puts "  artifact         : #{result[:artifact_path]}"
     puts "  size             : #{result[:size_bytes]} bytes"
-    puts "  CLAUDE.md region : #{result[:region_written] ? 'updated' : 'not updated (host file outside project root or unsafe)'}"
+    puts "  #{ctx_file} region : #{result[:region_written] ? 'updated' : 'not updated (host file outside project root or unsafe)'}"
     puts ""
-    puts "Restart Claude Code to apply (CLAUDE.md @-imports resolve at session start)."
+    puts "Restart the host to apply (#{ctx_file} is read at session start)."
     exit 0
 
   when 'status'
     s = projector.instruction_mode_status
+    ctx_file = projector.host.context_file
     puts "Project root        : #{project_root} (source: #{KairosMcp.consumer_project_root_source})"
     puts "Data dir            : #{KairosMcp.data_dir}"
+    puts "Host                : #{projector.host.key}"
     if s[:active]
       puts "Instruction mode projection: ACTIVE"
       puts "  mode      : #{s[:mode_name]}#{s[:mode_version] ? " v#{s[:mode_version]}" : ''}"
       puts "  artifact  : #{s[:artifact_path]} (#{s[:artifact_size]} bytes)"
-      puts "  region    : #{s[:region_present] ? 'present in CLAUDE.md' : 'absent'}"
+      puts "  region    : #{s[:region_present] ? "present in #{ctx_file}" : "absent from #{ctx_file}"}"
       puts "  projected : #{s[:projected_at]}"
     else
       puts "Instruction mode projection: not active for this project."
@@ -493,11 +519,12 @@ when 'mode'
 
   when 'remove'
     result = projector.remove_projected_instruction_mode!
-    puts "Instruction mode projection removed:"
+    ctx_file = projector.host.context_file
+    puts "Instruction mode projection removed (host: #{projector.host.key}):"
     puts "  artifact  : #{result[:artifact_removed] ? 'deleted' : 'not present'}"
-    puts "  CLAUDE.md : #{result[:region_removed] ? 'region removed' : 'region not present'}"
+    puts "  #{ctx_file} : #{result[:region_removed] ? 'region removed' : 'region not present'}"
     puts ""
-    puts "Restart Claude Code to apply (CLAUDE.md @-imports resolve at session start)."
+    puts "Restart the host to apply (#{ctx_file} is read at session start)."
     exit 0
 
   else

data/bin/kairos-plugin-project

@@ -17,7 +17,27 @@ require_relative '../lib/kairos_mcp/skillset_manager'
 
 project_root = KairosMcp.project_root
 mode = KairosMcp.projection_mode
-projector = KairosMcp::PluginProjector.new(project_root, mode: mode)
+
+# 2026-07-02: target host for projection (claude | codex | opencode). Default claude.
+# Used both for manual invocation and by projected re-projection hooks (--host <host>).
+host = 'claude'
+if (idx = ARGV.index('--host'))
+  host = ARGV[idx + 1]
+  if host.nil? || host.start_with?('--')
+    warn "ERROR: --host requires a value (claude, codex, or opencode)."
+    exit 1
+  end
+  ARGV.delete_at(idx + 1)
+  ARGV.delete_at(idx)
+end
+
+begin
+  projector = KairosMcp::PluginProjector.new(project_root, mode: mode, host: host)
+rescue ArgumentError => e
+  warn "ERROR: #{e.message}"
+  warn "  Valid --host values: claude, codex, opencode."
+  exit 1
+end
 
 if ARGV.include?('--status')
   require 'json'

data/lib/kairos_mcp/plugin_projector.rb

@@ -26,8 +26,79 @@ module KairosMcp
     INSTRUCTION_MODE_REL_PATH     = 'kairos/instruction_mode.md'
     INSTRUCTION_MODE_SIZE_WARN    = 150 * 1024
     INSTRUCTION_MODE_SIZE_REFUSE  = 256 * 1024
+    # Inline delivery (AGENTS.md) can be truncated by a host's context-file byte cap
+    # (e.g. Codex project-doc limit), so warn earlier than the artifact thresholds above.
+    INSTRUCTION_MODE_INLINE_WARN  = 32 * 1024
+
+    # Host-specific projection profile (2026-07-02, Codex support).
+    # Encapsulates per-host layout / context-file / instruction-mode delivery
+    # differences so the projection engine stays host-agnostic. See
+    # log/20260702_codex_projection_and_mcp_reviewer_implementation_plan.md
+    class HostProfile
+      attr_reader :key, :output_subdir, :context_file, :instruction_mode_delivery, :manifest_suffix,
+                  :hooks_strategy, :skill_projection, :agents_subdir, :agents_format
+
+      # @param skill_projection [Symbol] :own (project skills into this host) or
+      #   :reuse_claude (host reads .claude/skills/ directly — skip skill projection).
+      # @param agents_subdir [String] subdir under output_root for agents ('agents' or 'agent').
+      # @param agents_format [Symbol] :claude (verbatim) or :opencode (frontmatter converted).
+      def initialize(key:, output_subdir:, context_file:, instruction_mode_delivery:, manifest_suffix:,
+                     hooks_strategy:, skill_projection:, agents_subdir:, agents_format:)
+        @key = key
+        @output_subdir = output_subdir
+        @context_file = context_file
+        @instruction_mode_delivery = instruction_mode_delivery
+        @manifest_suffix = manifest_suffix
+        @hooks_strategy = hooks_strategy
+        @skill_projection = skill_projection
+        @agents_subdir = agents_subdir
+        @agents_format = agents_format
+      end
+
+      # Legacy manifest names carry no suffix so existing .kairos/ manifests keep working.
+      def manifest_filename(base)
+        @manifest_suffix ? "#{base}.#{@manifest_suffix}.json" : "#{base}.json"
+      end
+
+      # Claude Code: .claude/ layout, CLAUDE.md with @-import pointer, hooks in settings.json.
+      def self.claude_code
+        new(key: 'claude', output_subdir: '.claude', context_file: 'CLAUDE.md',
+            instruction_mode_delivery: :import, manifest_suffix: nil,
+            hooks_strategy: :claude_settings,
+            skill_projection: :own, agents_subdir: 'agents', agents_format: :claude)
+      end
+
+      # Codex CLI: .codex/ layout, AGENTS.md with inlined body (Codex does not resolve @-import).
+      # Hooks go to <repo>/.codex/hooks.json — same event structure as Claude, read natively by Codex.
+      def self.codex
+        new(key: 'codex', output_subdir: '.codex', context_file: 'AGENTS.md',
+            instruction_mode_delivery: :inline, manifest_suffix: 'codex',
+            hooks_strategy: :codex_hooks_json,
+            skill_projection: :own, agents_subdir: 'agents', agents_format: :claude)
+      end
+
+      # OpenCode: reads .claude/skills/ natively, so skills are NOT re-projected (Claude co-use
+      # assumption). AGENTS.md carries the inlined mode body (shared with Codex). Agents convert
+      # to .opencode/agent/ with OpenCode frontmatter. Hooks are JS/TS plugins → skipped.
+      def self.opencode
+        new(key: 'opencode', output_subdir: '.opencode', context_file: 'AGENTS.md',
+            instruction_mode_delivery: :inline, manifest_suffix: 'opencode',
+            hooks_strategy: :opencode_plugin,
+            skill_projection: :reuse_claude, agents_subdir: 'agent', agents_format: :opencode)
+      end
+
+      def self.for(host)
+        return host if host.is_a?(HostProfile)
+        case host.to_s
+        when 'claude', 'claude_code', 'claude-code' then claude_code
+        when 'codex' then codex
+        when 'opencode', 'open-code' then opencode
+        else raise ArgumentError, "unknown projection host: #{host.inspect}"
+        end
+      end
+    end
 
-    attr_reader :mode, :project_root, :output_root, :data_dir
+    attr_reader :mode, :project_root, :output_root, :data_dir, :host
 
     # Construct a PluginProjector.
     #
@@ -39,14 +110,15 @@ module KairosMcp
     #   data_dir = project_root/.kairos is used for manifest location (backward-compat).
     #
     # @raise [CoincidenceRefused] when project_root and data_dir resolve to the same real path
-    def initialize(project_root, mode: :auto, data_dir: nil)
+    def initialize(project_root, mode: :auto, data_dir: nil, host: :claude)
       @project_root = project_root
       @data_dir = data_dir || File.join(project_root, '.kairos')
       enforce_no_coincidence!
       @mode = resolve_mode(mode)
-      @output_root = @mode == :plugin ? project_root : File.join(project_root, '.claude')
-      @manifest_path = File.join(@data_dir, 'projection_manifest.json')
-      @instruction_mode_manifest_path = File.join(@data_dir, 'instruction_mode_manifest.json')
+      @host = HostProfile.for(host)
+      @output_root = @mode == :plugin ? project_root : File.join(project_root, @host.output_subdir)
+      @manifest_path = File.join(@data_dir, @host.manifest_filename('projection_manifest'))
+      @instruction_mode_manifest_path = File.join(@data_dir, @host.manifest_filename('instruction_mode_manifest'))
     end
 
     # Raised when project_root and data_dir resolve to the same real path (design Inv 3).
@@ -62,16 +134,20 @@ module KairosMcp
       current_outputs = {}
       merged_hooks = @mode == :plugin ? load_seed_hooks : { 'hooks' => {} }
 
+      # OpenCode reads .claude/skills/ directly (Claude co-use assumption), so it reuses the
+      # Claude skill projection instead of duplicating skills into .opencode/skills/.
+      reuse_skills = @host.skill_projection == :reuse_claude
+
       enabled_skillsets.each do |ss|
         next unless ss.has_plugin?
 
         plugin_dir = File.join(ss.path, 'plugin')
-        project_skill!(ss, plugin_dir, current_outputs)
+        project_skill!(ss, plugin_dir, current_outputs) unless reuse_skills
         project_agents!(ss, plugin_dir, current_outputs)
         collect_hooks!(ss, plugin_dir, merged_hooks)
       end
 
-      project_knowledge_meta_skill!(knowledge_entries, current_outputs)
+      project_knowledge_meta_skill!(knowledge_entries, current_outputs) unless reuse_skills
       write_merged_hooks!(merged_hooks, current_outputs)
       cleanup_stale!(previous_manifest, current_outputs)
       save_manifest(current_outputs, enabled_skillsets, knowledge_entries)
@@ -130,6 +206,11 @@ module KairosMcp
       size = body.bytesize
       raise InstructionModeTooLarge.new(size, INSTRUCTION_MODE_SIZE_REFUSE) if size > INSTRUCTION_MODE_SIZE_REFUSE
       warn "[PluginProjector] WARNING: instruction mode body is #{size} bytes (warn threshold #{INSTRUCTION_MODE_SIZE_WARN})" if size > INSTRUCTION_MODE_SIZE_WARN
+      if @host.instruction_mode_delivery == :inline && size > INSTRUCTION_MODE_INLINE_WARN
+        warn "[PluginProjector] WARNING: inlining #{size} bytes into #{@host.context_file}; " \
+             "host '#{@host.key}' may cap the context-file read (e.g. Codex project-doc byte limit). " \
+             "Raise the host's context-file byte cap if the projected mode body appears truncated."
+      end
 
       artifact_path = File.join(@output_root, INSTRUCTION_MODE_REL_PATH)
       raise "instruction mode artifact path outside output_root: #{artifact_path}" unless safe_path?(artifact_path)
@@ -137,7 +218,7 @@ module KairosMcp
       FileUtils.mkdir_p(File.dirname(artifact_path))
       atomic_write(artifact_path, body)
 
-      region_written = merge_instruction_mode_region!(mode_name, mode_version, artifact_path)
+      region_written = merge_instruction_mode_region!(mode_name, mode_version, artifact_path, body)
 
       save_instruction_mode_manifest(
         'mode_name' => mode_name,
@@ -184,11 +265,20 @@ module KairosMcp
         mode_version: manifest['mode_version'],
         artifact_path: manifest['artifact_path'],
         artifact_size: manifest['artifact_size'],
-        region_present: manifest['region_present'],
+        # Verify against the actual context file, not just the manifest: another host
+        # sharing AGENTS.md may have stripped the region since this host projected.
+        region_present: context_region_present?,
         projected_at: manifest['projected_at']
       }
     end
 
+    # True if the managed marker region currently exists in this host's context file.
+    def context_region_present?
+      path = claudemd_path
+      return false unless File.exist?(path)
+      File.read(path).include?(INSTRUCTION_MODE_MARKER_BEGIN)
+    end
+
     # Raised when a mode body exceeds the hard refusal threshold.
     class InstructionModeTooLarge < StandardError
       def initialize(size, limit)
@@ -283,14 +373,49 @@ module KairosMcp
       return unless Dir.exist?(agents_src)
       return unless safe_name?(ss.name)
       Dir.glob(File.join(agents_src, '*.md')).each do |f|
-        target = File.join(@output_root, 'agents', "#{ss.name}-#{File.basename(f)}")
+        target = File.join(@output_root, @host.agents_subdir, "#{ss.name}-#{File.basename(f)}")
         next unless safe_path?(target)
         FileUtils.mkdir_p(File.dirname(target))
-        atomic_write(target, File.read(f))
+        content = File.read(f)
+        content = convert_agent_to_opencode(content) if @host.agents_format == :opencode
+        atomic_write(target, content)
         outputs[target] = { 'source' => f, 'type' => 'agent', 'skillset' => ss.name }
       end
     end
 
+    # Convert a Claude Code agent (.md + YAML frontmatter) to OpenCode agent frontmatter.
+    #   - drop `name` (OpenCode derives the agent name from the filename)
+    #   - drop `model` (OpenCode subagents inherit the caller's model — free-LLM friendly)
+    #   - `disallowedTools: A, B` -> `tools: { a: false, b: false }`
+    #   - add `mode: subagent`
+    # Body (system prompt) is preserved verbatim. Returns input unchanged if no frontmatter.
+    def convert_agent_to_opencode(content)
+      m = content.match(/\A---\s*\n(.*?)\n---\s*\n?(.*)\z/m)
+      return content unless m
+
+      require 'yaml'
+      src = begin
+        YAML.safe_load(m[1])
+      rescue StandardError
+        return content
+      end
+      return content unless src.is_a?(Hash)
+      body = m[2]
+
+      out = {}
+      out['description'] = src['description'] if src['description']
+      out['mode'] = 'subagent'
+      if src['disallowedTools']
+        # Accept both comma-string ("Write, Edit") and YAML list ([Write, Edit]) forms.
+        disabled = Array(src['disallowedTools']).flat_map { |t| t.to_s.split(',') }
+                                                .map { |t| t.strip.downcase }.reject(&:empty?)
+        out['tools'] = disabled.each_with_object({}) { |t, h| h[t] = false } unless disabled.empty?
+      end
+
+      front = YAML.dump(out).sub(/\A---\n/, '').rstrip
+      "---\n#{front}\n---\n\n#{body.lstrip}"
+    end
+
     # =========================================================================
     # L1 Knowledge meta skill
     # =========================================================================
@@ -374,10 +499,79 @@ module KairosMcp
       if @mode == :plugin
         write_hooks_file!(merged_hooks, outputs)
       else
-        write_hooks_to_settings!(merged_hooks, outputs)
+        case @host.hooks_strategy
+        when :codex_hooks_json  then write_hooks_to_codex_json!(merged_hooks, outputs)
+        when :opencode_plugin   then skip_hooks_for_plugin_host!(merged_hooks)
+        else                         write_hooks_to_settings!(merged_hooks, outputs)
+        end
       end
     end
 
+    # Codex reads <repo>/.codex/hooks.json (same event structure as Claude hooks).
+    # KairosChain owns this file (overwrite), mirroring plugin-mode hooks/hooks.json.
+    # kairos-plugin-project commands are rewritten to re-project this same host.
+    def write_hooks_to_codex_json!(merged_hooks, outputs)
+      hooks_file = File.join(@output_root, 'hooks.json')
+      existing = load_settings(hooks_file) # {} when absent, nil on parse error
+      return if existing.nil?
+
+      # A hand-authored file may hold a malformed 'hooks' (non-Hash, or non-Array
+      # event values). Normalize before merging so projection never crashes; a
+      # malformed 'hooks' carries no preservable user hooks anyway.
+      existing['hooks'] = {} unless existing['hooks'].is_a?(Hash)
+      existing['hooks'].transform_values! { |v| v.is_a?(Array) ? v : [] }
+
+      # Strip previously projected entries, preserving user-authored (untagged) hooks —
+      # mirrors the Claude settings.json path so re-projection never destroys user hooks.
+      existing['hooks'].each_value do |handlers|
+        handlers.reject! { |h| h.is_a?(Hash) && h['_projected_by'] == PROJECTED_BY }
+      end
+      existing['hooks'].delete_if { |_, v| v.empty? }
+
+      projected = rewrite_hook_commands_for_host(merged_hooks)
+      unless projected['hooks'].empty?
+        projected['hooks'].each do |event, handlers|
+          existing['hooks'][event] ||= []
+          existing['hooks'][event].concat(handlers.map { |h| h.merge('_projected_by' => PROJECTED_BY) })
+        end
+      end
+
+      existing.delete('hooks') if existing['hooks'].empty?
+      # Only delete the file if nothing (projected or user) remains — never clobber user content.
+      if existing.empty?
+        FileUtils.rm_f(hooks_file)
+        return
+      end
+      FileUtils.mkdir_p(File.dirname(hooks_file))
+      atomic_write(hooks_file, JSON.pretty_generate(existing))
+      outputs[hooks_file] = { 'type' => 'hooks_codex_json' }
+    end
+
+    # OpenCode hooks are JS/TS plugins, not a declarative file — cannot be projected here.
+    def skip_hooks_for_plugin_host!(merged_hooks)
+      return if merged_hooks['hooks'].empty?
+      warn "[PluginProjector] WARNING: host '#{@host.key}' uses plugin-based hooks (JS/TS); " \
+           "skipping projection of #{merged_hooks['hooks'].size} hook event(s). Author an OpenCode plugin instead."
+    end
+
+    # Ensure projected re-projection hooks target THIS host, not the default (claude).
+    # Deep-copies so the shared merged_hooks (used by other hosts) is not mutated.
+    def rewrite_hook_commands_for_host(merged_hooks)
+      copy = JSON.parse(JSON.generate(merged_hooks))
+      copy.fetch('hooks', {}).each_value do |handlers|
+        next unless handlers.is_a?(Array)
+        handlers.each do |h|
+          Array(h['hooks']).each do |inner|
+            cmd = inner['command']
+            next unless cmd.is_a?(String) && cmd.include?('kairos-plugin-project') && !cmd.include?('--host')
+            # Insert right after the binary token so compound commands (a && b) stay correct.
+            inner['command'] = cmd.sub('kairos-plugin-project', "kairos-plugin-project --host #{@host.key}")
+          end
+        end
+      end
+      copy
+    end
+
     # Plugin mode: write hooks/hooks.json
     def write_hooks_file!(merged_hooks, outputs)
       hooks_dir = File.join(@output_root, 'hooks')
@@ -457,12 +651,12 @@ module KairosMcp
       current_files = current_outputs.keys
       stale = previous_files - current_files
       stale.each do |f|
-        # Path safety: only delete files under output_root
-        canonical = File.expand_path(f)
-        unless canonical.start_with?(File.expand_path(@output_root))
+        # Path safety: only delete files under output_root (separator-boundary check)
+        unless within_output_root?(f)
           warn "[PluginProjector] WARNING: skipping stale cleanup of '#{f}' (outside output_root)"
           next
         end
+        canonical = File.expand_path(f)
         FileUtils.rm_f(canonical)
         dir = File.dirname(canonical)
         FileUtils.rmdir(dir) if Dir.exist?(dir) && Dir.empty?(dir)
@@ -507,7 +701,7 @@ module KairosMcp
     def find_orphaned_files(manifest_outputs)
       projected_dirs = [
         File.join(@output_root, 'skills'),
-        File.join(@output_root, 'agents')
+        File.join(@output_root, @host.agents_subdir)
       ]
       actual_files = projected_dirs.flat_map do |dir|
         next [] unless Dir.exist?(dir)
@@ -532,10 +726,17 @@ module KairosMcp
       true
     end
 
+    # True if path is exactly output_root or a descendant. Uses a separator boundary
+    # so a sibling like '<root>/.codex_backup' does not match the '<root>/.codex' prefix.
+    def within_output_root?(path)
+      root = File.expand_path(@output_root)
+      canonical = File.expand_path(path)
+      canonical == root || canonical.start_with?(root + File::SEPARATOR)
+    end
+
     # Validate target path is under output_root
     def safe_path?(target)
-      canonical = File.expand_path(target)
-      unless canonical.start_with?(File.expand_path(@output_root))
+      unless within_output_root?(target)
         warn "[PluginProjector] WARNING: path '#{target}' is outside output_root, skipping"
         return false
       end
@@ -570,16 +771,26 @@ module KairosMcp
 
     # Merge or insert the managed marker region in project-root CLAUDE.md.
     # Returns true if the region is now present, false otherwise.
-    def merge_instruction_mode_region!(mode_name, mode_version, artifact_path)
+    def merge_instruction_mode_region!(mode_name, mode_version, artifact_path, body)
       claudemd = claudemd_path
       return false unless safe_claudemd_path?(claudemd)
 
-      import_path = relative_import_path(artifact_path)
       header = "<!-- Active mode: #{mode_name}#{mode_version ? " v#{mode_version}" : ''} | source: .kairos/skills/#{mode_name}.md -->"
+      # Claude Code resolves @-import at session start (pointer). Codex does not,
+      # so its body is inlined directly into AGENTS.md.
+      payload = case @host.instruction_mode_delivery
+                when :inline then body
+                else "@#{relative_import_path(artifact_path)}"
+                end
+      if @host.instruction_mode_delivery == :inline &&
+         (body.include?(INSTRUCTION_MODE_MARKER_BEGIN) || body.include?(INSTRUCTION_MODE_MARKER_END))
+        warn "[PluginProjector] WARNING: inlined mode body contains an instruction-mode marker; " \
+             "re-projection region detection may be unreliable for #{@host.context_file}."
+      end
       region = [
         INSTRUCTION_MODE_MARKER_BEGIN,
         header,
-        "@#{import_path}",
+        payload,
         INSTRUCTION_MODE_MARKER_END
       ].join("\n")
 
@@ -607,9 +818,9 @@ module KairosMcp
       true
     end
 
-    # Project-root CLAUDE.md absolute path.
+    # Project-root context file absolute path (CLAUDE.md for Claude, AGENTS.md for Codex).
     def claudemd_path
-      File.join(@project_root, 'CLAUDE.md')
+      File.join(@project_root, @host.context_file)
     end
 
     # Path safety for the host file: must be exactly <project_root>/CLAUDE.md.
@@ -618,7 +829,7 @@ module KairosMcp
       canonical = File.expand_path(path)
       expected = File.expand_path(claudemd_path)
       return true if canonical == expected
-      warn "[PluginProjector] WARNING: refusing to mutate non-project CLAUDE.md at '#{path}'"
+      warn "[PluginProjector] WARNING: refusing to mutate non-project #{@host.context_file} at '#{path}'"
       false
     end
 

data/lib/kairos_mcp/version.rb

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

data/templates/knowledge/loop_engineering_patterns/loop_engineering_patterns.md

@@ -0,0 +1,49 @@
+---
+name: loop_engineering_patterns
+description: Use before designing or classifying an agent loop in KairosChain — to pick a loop type, apply loop-design craft, and place each loop at the right layer under the Prop 10 floor. Claude Code's four loop types + design principles, extended with the governance constraint Anthropic omits.
+version: "0.3"
+tags: [loops, agent, autonomy, taxonomy, layer-placement, provenance]
+---
+
+# Loop Engineering Patterns
+
+Distilled from Claude Code's post [Getting Started with Loops](https://claude.com/blog/getting-started-with-loops) (Anthropic, 2026). Local provenance / facts index: `references/claude_code_loops_2026.md` (pointer; canonical text is the URL, not redistributed here). Sibling method: [[skill_authoring_patterns]] — same distill-an-Anthropic-post-through-KairosChain-layers move.
+
+## When to reference this entry
+Open *before* designing or classifying an agent loop — not a runtime tool:
+- New agent loop / autonomous cycle → pick a §A type, apply §B craft, then place it via §C.
+- "Which layer owns this loop?" (harness vs gem/SkillSet, plus the cross-cutting L0 governance floor) → §C table + the L0 note below it.
+- Strengthening the `agent` OODA loop (self-verification, semantic stop) → §B + §C evaluator/verifier notes.
+- Explaining why KairosChain's autonomous mode keeps human checkpoints → §C Prop 10 floor.
+- Not for: skill lifecycle/maturation → [[agent_skill_evolution_guide]]; general layer rules → [[layer_placement_guide]].
+
+## A. Four loop types (base-level classification)
+Two axes generate the four types: **trigger** (user prompt / goal spec / schedule-or-event) and **human presence** (present / absent). The autonomous type is the no-human variant of the schedule/event trigger, not a fourth independent trigger — kept as a peer type here to mirror the source taxonomy.
+1. **Turn-driven** — trigger: user prompt; stop: task done or needs context; for short exploratory work.
+2. **Goal-driven** — trigger: goal spec (`/goal`); stop: goal met OR max turns; a separate evaluator checking exit criteria raises reliability; for tasks with verifiable exit.
+3. **Time-driven** — trigger: schedule/interval (`/loop`, `/schedule`); stop: user cancels or work done; for recurring work / external monitoring.
+4. **Autonomous** — trigger: events/schedule, no human present; stop: each task exits on goal, routine runs until disabled; for well-defined recurring streams (triage, migrations).
+
+Micro (small) and macro (broad) loops compose; match loop complexity to problem abstraction.
+
+## B. Design craft (universal — adopt as-is)
+Output quality tracks the surrounding harness, not the model alone. Keep the codebase clean so the loop follows existing patterns. **Encode verification as a skill with quantitative checks** so the loop measures its own work. Keep docs accessible/current. **Use a second, independent agent for review** (fresh context, separate session/model). Set explicit success/stop criteria and max-turn caps to bound cost; script deterministic steps instead of re-reasoning them; monitor token spend.
+
+## C. KairosChain reading (layer placement + the floor Anthropic omits)
+The four types are harness-framed (`/goal`, `/loop`, `/schedule`, `/usage`, auto mode are Claude Code mechanisms). KairosChain already implements most of the substance across layers — so the work is mostly *placement*, not adoption; one item is still design-stage (flagged in the table):
+
+| Type | KairosChain home | Existing mechanism (status) |
+|---|---|---|
+| Turn-driven | harness (Claude Code) | interactive session (shipped) |
+| Goal-driven | gem / SkillSet | `agent` OODA loop with explicit goal + max-step cap; goal-satisfaction judged from reflect-phase confidence/remaining, human-mediated stop (shipped). The *wired* auto-exit on confidence is the Autonomous row's Gate 7, not this path. |
+| Time-driven | harness / gem | harness: `/loop`, `/schedule`, ScheduleWakeup/Cron (shipped, harness-layer); gem: routines × autonomous-growth (design, not yet shipped) |
+| Autonomous | gem | `autonomos_cycle`/`loop`, `autoexec`, and the `agent` autonomous path — whose Gate 7 confidence early-exit (`confidence_exit_threshold`, wired in `agent_step.rb`) terminates on goal satisfaction (shipped) |
+
+**L0 (cross-cutting, not a per-type home):** the Prop 10 procedural floor binds every row — it is a governance constraint over all four types, not a home for any one. See the paragraph below.
+
+The article's craft maps onto existing mechanisms (illustratively, not as strict 1:1 equivalences): its "separate evaluator" for goal-driven ≈ the agent's reflect-phase confidence evaluation (Observe/Reflect), not `multi_llm_review`; "verification as skill" ≈ `introspection_check` / `definition_verify`; "second agent for review" ≈ `multi_llm_review` (independent session). These pre-exist; they are not new imports.
+
+**The governance floor Anthropic omits.** Every article loop optimizes for completion/throughput; none carries a consent/audit constraint. KairosChain adds a cross-cutting axis: **every loop, whatever its type, is bound by the Prop 10 procedural floor** — no loop may bypass consent, harm protection, or audit, and any autonomous norm must stay recordable and contestable. (Prop 10 is currently provisional/inline in masa mode, not yet promoted to L0; the floor it names is nonetheless the intended binding.) Concretely, the autonomous type's "run until disabled, no human present" cannot be adopted verbatim: KairosChain's autonomous loop carries human checkpoints and safety gates (the `agent` skill), and a stop is not a bare exit but a constitutively recorded Kairos moment (Prop 5). This floor is the KairosChain-specific delta — the article has no place for it because a weight-hosted assistant has no revisable governance surface. Consistent with (not proof of) masa mode's harness-as-cultivation-surface bet in [[skill_authoring_patterns]] §C.
+
+## Related
+[[skill_authoring_patterns]] · [[layer_placement_guide]] · [[agent_skill_evolution_guide]] (instance-local, not gem-bundled) · [[kairoschain_self_development]] · kairoschain_meta_philosophy (Prop 5 constitutive recording). Prop 10 procedural floor: current authoritative home is masa mode § Proposition 10 (inline, provisional); migration into L1/L0 is pending.

data/templates/knowledge/loop_engineering_patterns/references/claude_code_loops_2026.md

@@ -0,0 +1,23 @@
+# [Source pointer] Getting Started with Loops
+
+> **Provenance / 来歴**
+> - **Source (official):** https://claude.com/blog/getting-started-with-loops
+> - **Publisher:** Anthropic / Claude Code
+> - **Retrieved:** 2026-07-03
+> - **Companion:** JP video walkthrough ("【神記事】Claude Code 公式が遂に『ループエンジニアリング』を解説") — user-supplied summary; canonical URL not recorded.
+>
+> **This is a pointer, not a copy.** The article's text is Anthropic's
+> copyrighted content and is **not redistributed in this gem**. The canonical
+> source is the URL above.
+
+## What the source covers (facts, for indexing)
+
+**Four loop types:** turn-driven (trigger: user prompt; stop: task done or needs context) · goal-driven (`/goal`; stop: goal met OR max turns; a separate evaluator model checks exit criteria) · time-driven (`/loop`, `/schedule`; stop: user cancels or work done) · autonomous/proactive (events/schedule, no human present; each task exits on goal, routine runs until disabled).
+
+**Design principles:** maintain clean codebases; encode verification as skills with quantitative checks; keep documentation accessible/current; deploy a second independent agent for review. Micro/macro loops compose — match loop complexity to problem abstraction.
+
+**Operational notes:** bound cost with explicit success criteria + max-turn caps; script deterministic work rather than re-reasoning it; monitor spend (`/usage`, `/goal` metrics, `/workflows`); match scheduling interval to actual change frequency; auto mode removes manual permission for routine execution.
+
+**Slash examples:** `/goal get the homepage Lighthouse score to 90 or above, stop after 5 tries` · `/loop 5m check my PR, address review comments, and fix failing CI` · `/schedule every hour: check #project-feedback for bug reports`.
+
+For the KairosChain reading through layers, see `loop_engineering_patterns.md` §A/§B/§C. For full prose, open the URL above.

data/templates/knowledge/skill_authoring_patterns/skill_authoring_patterns.md

@@ -44,4 +44,4 @@ The real difference is *where philosophy lives*: closed in the core (Anthropic)
 **Why this bet (operational vs decorative).** Harness-hosted norms are readable/recorded/revisable where weight-baked norms are opaque (Prop 10, provisional in masa.md) — arguably the right home even post-fine-tuning. Hiring a model ≠ cultivating one; the harness is the weight-less user's only cultivation surface. Norms must stay operational (hooks, introspection_check), not decorative (philosophy theater). Full dialogue: `references/why_harness_norms_bet.md`.
 
 ## Related
-[[agent_skill_evolution_guide]] · skillset_implementation_quality_guide · kairoschain_meta_philosophy (Prop 1; Prop 10 provisional in masa.md).
+[[agent_skill_evolution_guide]] · [[loop_engineering_patterns]] (sibling: same distill-an-Anthropic-post-through-layers method) · skillset_implementation_quality_guide · kairoschain_meta_philosophy (Prop 1; Prop 10 provisional in masa.md).

data/templates/skillsets/llm_client/lib/llm_client/call_router.rb

@@ -135,6 +135,7 @@ module KairosMcp
           c['dispatch_id']  = args['dispatch_id']  if args['dispatch_id']
           c['sandbox_mode'] = true                  if args['sandbox_mode']
           c['effort']       = args['effort']        if args['effort']
+          c['backend']      = args['backend']       if args['backend']
           c
         end
 
@@ -147,8 +148,13 @@ module KairosMcp
             require_relative 'claude_code_adapter'
             ClaudeCodeAdapter.new(config)
           when 'codex'
-            require_relative 'codex_adapter'
-            CodexAdapter.new(config)
+            if config['backend'].to_s == 'mcp'
+              require_relative 'codex_mcp_adapter'
+              CodexMcpAdapter.new(config)
+            else
+              require_relative 'codex_adapter'
+              CodexAdapter.new(config)
+            end
           when 'cursor'
             require_relative 'cursor_adapter'
             CursorAdapter.new(config)

data/templates/skillsets/llm_client/lib/llm_client/codex_mcp_adapter.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require_relative 'adapter'
+
+module KairosMcp
+  module SkillSets
+    module LlmClient
+      # Adapter that drives OpenAI Codex through its MCP server (`codex mcp-server`)
+      # rather than `codex exec`. Spawns the server over stdio, performs the MCP
+      # handshake, invokes the `codex` tool once (sandbox read-only by default so a
+      # reviewer/eval call cannot mutate the workspace), and returns the normalized
+      # response. One-shot: the server is started and torn down per call.
+      #
+      # Companion to CodexAdapter (CLI). Selectable as the codex backend in
+      # multi_llm_review / cross-eval to A/B the MCP path against `codex exec`.
+      class CodexMcpAdapter < Adapter
+        DEFAULT_TIMEOUT = 300
+        PROTOCOL_VERSION = '2025-06-18'
+
+        def call(messages:, system: nil, tools: nil, model: nil,
+                 max_tokens: nil, temperature: nil, output_schema: nil)
+          prompt = build_prompt(messages, system, output_schema)
+          sandbox = @config&.dig('sandbox') || 'read-only' # reviewers/evals must not mutate
+          timeout = (@config&.dig('timeout_seconds') || DEFAULT_TIMEOUT).to_i
+
+          result = run_codex_tool(prompt: prompt, model: model, sandbox: sandbox, timeout: timeout)
+
+          {
+            'content' => result[:text],
+            'tool_use' => nil,
+            'stop_reason' => 'end_turn',
+            'model' => model || 'codex-mcp-default',
+            'thread_id' => result[:thread_id],
+            'input_tokens' => nil,
+            'output_tokens' => nil
+          }
+        rescue ApiError
+          raise
+        rescue Errno::ENOENT
+          raise ApiError.new('codex CLI not found. Install: https://github.com/openai/codex',
+                             provider: 'codex', retryable: false)
+        rescue StandardError => e
+          raise ApiError.new("codex mcp error: #{e.message}", provider: 'codex')
+        end
+
+        private
+
+        def run_codex_tool(prompt:, model:, sandbox:, timeout:)
+          args = { 'prompt' => prompt, 'sandbox' => sandbox,
+                   'approval-policy' => (@config&.dig('approval_policy') || 'never') }
+          args['model'] = model.to_s if model && !model.to_s.empty?
+
+          stdin, stdout, wait = Open3.popen2('codex', 'mcp-server')
+          deadline = now + timeout
+          begin
+            send_msg(stdin, id: 1, method: 'initialize', params: {
+                       'protocolVersion' => PROTOCOL_VERSION, 'capabilities' => {},
+                       'clientInfo' => { 'name' => 'kairos-chain', 'version' => '0.1' }
+                     })
+            read_result(stdout, 1, deadline)
+            send_msg(stdin, method: 'notifications/initialized')
+
+            send_msg(stdin, id: 2, method: 'tools/call',
+                     params: { 'name' => 'codex', 'arguments' => args })
+            resp = read_result(stdout, 2, deadline)
+            extract(resp)
+          ensure
+            stdin.close unless stdin.closed?
+            unless wait.join(3)
+              begin
+                Process.kill('TERM', wait.pid)
+              rescue StandardError
+                nil
+              end
+            end
+            stdout.close unless stdout.closed?
+          end
+        end
+
+        def send_msg(io, method:, id: nil, params: nil)
+          msg = { 'jsonrpc' => '2.0', 'method' => method }
+          msg['id'] = id if id
+          msg['params'] = params if params
+          io.puts(JSON.generate(msg))
+          io.flush
+        end
+
+        # Read newline-delimited JSON-RPC until a response with the given id arrives,
+        # skipping notifications/progress and unrelated lines. Raises on timeout/error.
+        def read_result(io, id, deadline)
+          loop do
+            remaining = deadline - now
+            timed_out!(id) if remaining <= 0
+            timed_out!(id) unless IO.select([io], nil, nil, remaining)
+            line = io.gets
+            raise ApiError.new('codex mcp server closed the connection unexpectedly',
+                               provider: 'codex', retryable: true) if line.nil?
+            line = line.strip
+            next if line.empty?
+            begin
+              msg = JSON.parse(line)
+            rescue JSON::ParserError
+              next
+            end
+            next unless msg['id'] == id
+            if msg['error']
+              raise ApiError.new("codex mcp error: #{msg['error']['message'] || msg['error']}",
+                                 provider: 'codex')
+            end
+            return msg['result']
+          end
+        end
+
+        def timed_out!(id)
+          raise ApiError.new("codex mcp timed out waiting for id=#{id}",
+                             provider: 'codex', retryable: true)
+        end
+
+        def extract(result)
+          text = +''
+          thread_id = nil
+          if result.is_a?(Hash)
+            Array(result['content']).each do |blk|
+              text << blk['text'].to_s if blk.is_a?(Hash) && blk['type'] == 'text'
+            end
+            thread_id = result.dig('structuredContent', 'threadId') ||
+                        result.dig('_meta', 'threadId') || result['threadId']
+          end
+          { text: text, thread_id: thread_id }
+        end
+
+        def build_prompt(messages, system, output_schema)
+          parts = []
+          parts << "[System]: #{system}\n" if system
+          if output_schema
+            parts << '[Output Format]: Respond with ONLY valid JSON (no markdown fences) matching this schema:'
+            parts << JSON.generate(output_schema)
+            parts << ''
+          end
+          messages.each do |m|
+            role = m['role'] || m[:role]
+            content = m['content'] || m[:content]
+            case role
+            when 'user' then parts << content.to_s
+            when 'assistant' then parts << "[Previous assistant response]: #{content}"
+            when 'tool' then parts << "[Tool result]: #{content}"
+            end
+          end
+          parts.join("\n")
+        end
+
+        def now
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/llm_client/tools/llm_call.rb

@@ -99,6 +99,11 @@ module KairosMcp
                     'claude_code: low/medium/high/xhigh/max. ' \
                     'codex: minimal/low/medium/high. ' \
                     'Ignored by providers that do not support it.'
+                },
+                backend: {
+                  type: 'string',
+                  description: 'Provider transport backend. codex: "cli" (default, `codex exec`) ' \
+                    'or "mcp" (`codex mcp-server`, read-only sandbox). Ignored by other providers.'
                 }
               },
               required: ['messages']
@@ -134,6 +139,7 @@ module KairosMcp
             config['dispatch_id'] = arguments['dispatch_id'] if arguments['dispatch_id']
             config['sandbox_mode'] = true if arguments['sandbox_mode']
             config['effort'] = arguments['effort'] if arguments['effort']
+            config['backend'] = arguments['backend'] if arguments['backend']
 
             actual_provider = config['provider']
             adapter = build_adapter(config)
@@ -252,8 +258,13 @@ module KairosMcp
             when 'claude_code'
               ClaudeCodeAdapter.new(config)
             when 'codex'
-              require_relative '../lib/llm_client/codex_adapter'
-              CodexAdapter.new(config)
+              if config['backend'].to_s == 'mcp'
+                require_relative '../lib/llm_client/codex_mcp_adapter'
+                CodexMcpAdapter.new(config)
+              else
+                require_relative '../lib/llm_client/codex_adapter'
+                CodexAdapter.new(config)
+              end
             when 'cursor'
               require_relative '../lib/llm_client/cursor_adapter'
               CursorAdapter.new(config)

data/templates/skillsets/multi_llm_review/config/multi_llm_review.yml

@@ -128,6 +128,11 @@ reviewers:
   # GPT-5.5 added 2026-04-24 for benchmarking against gpt-5.4. Both codex
   # entries dispatch via the same `codex exec` CLI; the adapter passes
   # `-m <model>` so the response can be attributed per-model.
+  #
+  # Transport backend (2026-07-03): codex entries default to the `codex exec` CLI.
+  # Add `backend: mcp` to route a codex reviewer through `codex mcp-server` instead
+  # (CodexMcpAdapter, read-only sandbox). Opt-in for A/B against the CLI path;
+  # keep the default CLI until MCP parity is confirmed (see log 20260702 Appendix F).
   - provider: codex
     model: gpt-5.5
     effort: medium

data/templates/skillsets/multi_llm_review/lib/multi_llm_review/dispatcher.rb

@@ -161,6 +161,10 @@ module KairosMcp
           effort = reviewer[:effort] || reviewer['effort']
           args['effort'] = effort if effort
 
+          # Per-reviewer transport backend (codex: "cli" default | "mcp"). Opt-in.
+          backend = reviewer[:backend] || reviewer['backend']
+          args['backend'] = backend if backend
+
           # Pass dispatch_id and sandbox_mode to llm_call for adapter config.
           args['dispatch_id'] = dispatch_id
           args['sandbox_mode'] = true if review_context == 'independent'

data/templates/skillsets/plugin_projector/tools/plugin_project.rb

@@ -39,6 +39,12 @@ module KairosMcp
                 force: {
                   type: 'boolean',
                   description: 'Force re-projection ignoring digest check (project command only)'
+                },
+                host: {
+                  type: 'string',
+                  enum: %w[claude codex opencode],
+                  description: 'Target host (default claude). claude=.claude/ + settings.json; ' \
+                    'codex=.codex/ + .codex/hooks.json; opencode=.opencode/ (hooks skipped).'
                 }
               },
               required: %w[command]
@@ -51,7 +57,9 @@ module KairosMcp
 
             project_root = ::KairosMcp.project_root
             mode = ::KairosMcp.projection_mode
-            projector = ::KairosMcp::PluginProjector.new(project_root, mode: mode)
+            host = arguments['host'] || 'claude'
+            projector = ::KairosMcp::PluginProjector.new(project_root, mode: mode, host: host)
+            reload_hint = host == 'claude' ? ' Run /reload-plugins to activate.' : ''
 
             case arguments['command']
             when 'project'
@@ -64,15 +72,17 @@ module KairosMcp
                 text_content(JSON.pretty_generate({
                   status: 'projected',
                   mode: mode,
+                  host: host,
                   force: true,
-                  message: 'Run /reload-plugins to activate new skills.'
+                  message: "Projected to #{host}.#{reload_hint}"
                 }))
               else
                 changed = projector.project_if_changed!(enabled, knowledge_entries: knowledge_entries)
                 text_content(JSON.pretty_generate({
                   status: changed ? 'projected' : 'unchanged',
                   mode: mode,
-                  message: changed ? 'Run /reload-plugins to activate new skills.' : 'No changes detected.'
+                  host: host,
+                  message: changed ? "Projected to #{host}.#{reload_hint}" : 'No changes detected.'
                 }))
               end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kairos-chain
 version: !ruby/object:Gem::Version
-  version: 3.31.0
+  version: 3.34.0
 platform: ruby
 authors:
 - Masaomi Hatakeyama
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-10 00:00:00.000000000 Z
+date: 2026-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -275,6 +275,8 @@ files:
 - templates/knowledge/llm_cross_evaluation/scripts/test_calibration_v23.rb
 - templates/knowledge/llm_cross_evaluation/scripts/test_intra_family_v23.rb
 - templates/knowledge/llm_cross_evaluation/scripts/test_layer_d_v23.rb
+- templates/knowledge/loop_engineering_patterns/loop_engineering_patterns.md
+- templates/knowledge/loop_engineering_patterns/references/claude_code_loops_2026.md
 - templates/knowledge/mcp_to_saas_development_workflow/mcp_to_saas_development_workflow.md
 - templates/knowledge/multi_agent_design_workflow/multi_agent_design_workflow.md
 - templates/knowledge/multi_agent_design_workflow_jp/multi_agent_design_workflow_jp.md
@@ -459,6 +461,7 @@ files:
 - templates/skillsets/llm_client/lib/llm_client/call_router.rb
 - templates/skillsets/llm_client/lib/llm_client/claude_code_adapter.rb
 - templates/skillsets/llm_client/lib/llm_client/codex_adapter.rb
+- templates/skillsets/llm_client/lib/llm_client/codex_mcp_adapter.rb
 - templates/skillsets/llm_client/lib/llm_client/cursor_adapter.rb
 - templates/skillsets/llm_client/lib/llm_client/error_taxonomy.rb
 - templates/skillsets/llm_client/lib/llm_client/headless.rb