@zalom/plastic 1.1.4 → 1.2.0

package/PLASTIC.md

@@ -10,6 +10,7 @@ See `PLASTIC-reference.md` for reference material: read it on demand, it is not
 
 A directory in the store containing `{ID}--{slug}.md` and optional supporting files.
 It represents a desire: something a human or agent wants to accomplish, explore, or understand.
+The unit of work in Plastic is always an intent, never a ticket.
 
 ```
 store/

package/README.md

@@ -44,7 +44,7 @@ Plastic makes that thinking legible, resumable, and useful later.
 
 **Plastic is built for an AI-native developer, technical founder, or
 independent builder who works across multiple sessions, has ideas before
-they have tickets, and feels the cost of losing reasoning between agents,
+they have intents, and feels the cost of losing reasoning between agents,
 contexts, and days.**
 
 ## What it solves?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/codex-hook

@@ -0,0 +1,96 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+#
+# Usage: codex-hook <gate>   (gate: code-gate | lock-gate | savepoint-pre | gate-check | create-gate)
+#
+# The Codex input adapter (intent 102). Reads a Codex hook stdin payload
+# (session_id at top level, the apply_patch command in tool_input.command,
+# [guide Part 4]), parses the diff envelope via ApplyPatchEnvelope, and drives
+# Plastic's payload-agnostic Ruby gate/savepoint cores once per file operation.
+# The cores' output contracts are already Codex-compatible, so their stdout/
+# stderr/exit are relayed unchanged (see ACTION_1's ARGV-contract table).
+require "json"
+require "rbconfig"
+require_relative "lib/apply_patch_envelope"
+require_relative "lib/intent_validator"
+
+gate = ARGV[0].to_s
+raw = ($stdin.read rescue nil)
+exit 0 if raw.nil? || raw.strip.empty?
+payload = (JSON.parse(raw) rescue nil)
+exit 0 unless payload.is_a?(Hash)
+
+session = payload["session_id"].to_s
+command = payload.dig("tool_input", "command") || payload.dig("tool_params", "command")
+ops = ApplyPatchEnvelope.parse(command)
+exit 0 if ops.empty? # fail-open: nothing parseable to gate
+
+CORES = __dir__ # ~/.plastic/scripts
+def run_core(name, *argv)
+  out = IO.popen([RbConfig.ruby, File.join(CORES, name), *argv], "r", err: [:child, :out], &:read)
+  [out, $?.exitstatus]
+end
+
+def intent_file?(path)
+  abs = File.expand_path(path)
+  dir = File.dirname(abs)
+  dir.match?(%r{/store/[^/]+--[^/]+\z}) && File.basename(abs) == "#{File.basename(dir)}.md"
+end
+
+case gate
+when "create-gate"
+  # Pre-write veto: born-complete validation for Add ops on intent files only.
+  # Update/Delete/Move defer to the PostToolUse gate-check backstop (spec Decision 5).
+  ops.each do |o|
+    next unless o.op == :add && intent_file?(o.path)
+    result = IntentValidator.validate_content(o.added_content.to_s)
+    next if result[:ok]
+    $stderr.puts "PLASTIC CREATE GATE - #{File.basename(o.path)} is not a valid intent:"
+    result[:errors].each { |e| $stderr.puts "  #{e}" }
+    $stderr.puts "Create intents via new-intent / plastic-intent-creating; do not hand-author them."
+    exit 2
+  end
+  exit 0
+
+when "lock-gate"
+  # Deny is signalled by JSON on stdout at exit 0. Relay the first deny.
+  ops.each do |o|
+    out, _ = run_core("hook-lock-gate", o.path, session)
+    if out.include?('"permissionDecision":"deny"') || out.include?('"permissionDecision": "deny"')
+      print out
+      exit 0
+    end
+  end
+  exit 0
+
+when "code-gate"
+  ops.each do |o|
+    out, code = run_core("hook-code-gate", o.path, session, o.added_content.to_s)
+    if code == 2
+      $stderr.print out
+      exit 2
+    end
+  end
+  exit 0
+
+when "gate-check"
+  last_allow = nil
+  ops.each do |o|
+    out, code = run_core("hook-gate-check", o.path, session)
+    if code == 2
+      print out # {"decision":"block",...}
+      exit 2
+    end
+    last_allow = out unless out.to_s.strip.empty?
+  end
+  print last_allow if last_allow
+  exit 0
+
+when "savepoint-pre"
+  ops.each { |o| run_core("hook-savepoint-pre", o.path) }
+  exit 0
+
+else
+  exit 0
+end

package/scripts/doctor.rb

@@ -34,7 +34,8 @@ class Doctor
 
   DEFAULT_AGENTS = {
     "claude" => { name: "Claude Code", dir: File.join(Dir.home, ".claude") },
-    "codex"  => { name: "Codex CLI",   dir: File.join(Dir.home, ".agents") },
+    "codex"  => { name: "Codex CLI",   dir: File.join(Dir.home, ".agents"),
+                  home_dir: File.join(Dir.home, ".codex") },
     "hermes" => { name: "Hermes",      dir: File.join(Dir.home, ".hermes") },
   }.freeze
 
@@ -980,6 +981,8 @@ class Doctor
     case agent_key
     when "claude"
       checks += check_claude_registration(agent_dir)
+    when "codex"
+      checks += check_codex_registration(agent_key, agent_dir)
     else
       checks += check_generic_agent_registration(agent_key, agent_dir)
     end
@@ -1196,9 +1199,11 @@ class Doctor
     end
   end
 
-  def check_generic_agent_registration(agent_key, agent_dir)
+  # Shared skills-presence plus stray-skills check, used by both the generic
+  # (hermes) agent-registration path and codex's TOML-based one. Neither the flat
+  # `.md` agents check nor anything agent-format-specific lives here.
+  def check_flat_skills_and_stray(agent_key, agent_dir)
     checks = []
-    config = agents[agent_key]
 
     # For codex/hermes: just check skills exist (no settings.json hooks)
     checks << flat_skills_check(agent_dir, "--#{agent_key}")
@@ -1208,11 +1213,162 @@ class Doctor
     stray_check = stray_skills_check(agent_dir, "--#{agent_key}", File.join(agent_dir, "plastic-manifest.json"))
     checks << stray_check if stray_check
 
-    checks << flat_agents_check(agent_dir, "--#{agent_key}")
+    checks
+  end
+
+  def check_generic_agent_registration(agent_key, agent_dir)
+    checks = check_flat_skills_and_stray(agent_key, agent_dir)
+    checks << flat_agents_check(agent_dir, "--#{agent_key}")   # hermes: unchanged (.md copy)
+    checks
+  end
+
+  # Codex marker literals. Keep in sync with InstallerCore::CODEX_SECTION_BEGIN_PREFIX /
+  # CODEX_SECTION_END (doctor does not require installer_core, so the literals are duplicated).
+  CODEX_SECTION_BEGIN_PREFIX = "<!-- BEGIN PLASTIC INTEGRATION"
+  CODEX_SECTION_END = "<!-- END PLASTIC INTEGRATION -->"
+
+  def check_codex_registration(agent_key, agent_dir)
+    config = agents[agent_key]
+    checks = check_flat_skills_and_stray(agent_key, agent_dir)
+    checks << codex_agents_toml_check(config)
+
+    agents_md = File.join(config[:home_dir], "AGENTS.md")
+
+    if !File.exist?(agents_md)
+      checks << check(
+        category: "agent_registration", name: "codex_agents_md", status: "fail",
+        message: "Codex AGENTS.md not found at #{tilde(agents_md)}",
+        fixable: true, fix_hint: "Re-run the Plastic installer with --codex"
+      )
+    else
+      content = File.read(agents_md)
+      b = content.index(CODEX_SECTION_BEGIN_PREFIX)
+      e = content.index(CODEX_SECTION_END)
+      well_formed = b && e && e > b && content[b...e].include?("-->")
+      if well_formed
+        checks << check(
+          category: "agent_registration", name: "codex_agents_md", status: "pass",
+          message: "Codex AGENTS.md carries the Plastic section"
+        )
+      else
+        checks << check(
+          category: "agent_registration", name: "codex_agents_md", status: "fail",
+          message: "Codex AGENTS.md is missing or has a malformed Plastic section",
+          fixable: true, fix_hint: "Re-run the Plastic installer with --codex"
+        )
+      end
+    end
+
+    checks << codex_hooks_registered_check(config)
+    codex_config_toml_advisory_check(config).tap { |c| checks << c if c }
 
     checks
   end
 
+  # Codex-specific agent presence + structural sanity: ~/.codex/agents/plastic-*.toml
+  # exist and each carries the mandatory fields. No TOML parser (doctor depends on none):
+  # "structural" means the mandatory keys appear as lines and the multi-line
+  # developer_instructions string is balanced (an opening triple-quote has a later one).
+  def codex_agents_toml_check(config)
+    agents_root = File.join(config[:home_dir], "agents")
+    found = Dir.glob(File.join(agents_root, "plastic-*.toml"))
+
+    if found.empty?
+      return check(
+        category: "agent_registration", name: "codex_agents_toml", status: "fail",
+        message: "No plastic-* agent TOML files found in #{tilde(agents_root)}",
+        fixable: true, fix_hint: "Re-run the Plastic installer with --codex"
+      )
+    end
+
+    malformed = found.reject { |f| codex_agent_toml_well_formed?(File.read(f)) }
+    if malformed.empty?
+      check(
+        category: "agent_registration", name: "codex_agents_toml", status: "pass",
+        message: "#{found.size} plastic-* agent TOML(s) installed in #{tilde(agents_root)}"
+      )
+    else
+      check(
+        category: "agent_registration", name: "codex_agents_toml", status: "fail",
+        message: "#{malformed.size} Codex agent TOML(s) missing mandatory fields",
+        details: malformed.map { |f| tilde(f) },
+        fixable: true, fix_hint: "Re-run the Plastic installer with --codex"
+      )
+    end
+  end
+
+  def codex_agent_toml_well_formed?(content)
+    marker = 'developer_instructions = """'
+    di = content.index(marker)
+    has_name = content.match?(/^name\s*=\s*"/)
+    has_desc = content.match?(/^description\s*=\s*"/)
+    balanced = di && content.index('"""', di + marker.length)
+    has_name && has_desc && !di.nil? && !balanced.nil?
+  end
+
+  # codex_hooks_registered (intent 102, the owner-facing first-run validation
+  # path, Decision 14): ~/.codex/hooks.json must carry EXACTLY the commands
+  # HookRegistry.codex_hooks_json defines, mirroring the Claude
+  # hooks_match_registry diff. Never writes.
+  def codex_hooks_registered_check(config)
+    hooks_json = File.join(config[:home_dir], "hooks.json")
+    dispatcher = File.join(plastic_home, "scripts", "codex-hook")
+    data = read_json_safe(hooks_json)
+
+    if data.nil?
+      return check(
+        category: "agent_registration", name: "codex_hooks_registered", status: "fail",
+        message: "Codex hooks.json missing or unreadable at #{tilde(hooks_json)}",
+        fixable: true, fix_hint: "Re-run the Plastic installer with --codex"
+      )
+    end
+
+    expected = HookRegistry.codex_hooks_json(dispatcher_path: dispatcher)
+    live = data["hooks"] || {}
+    missing = []
+    expected.each do |event, groups|
+      want = Array(groups).flat_map { |g| g["hooks"].map { |h| h["command"] } }
+      got = Array(live[event]).flat_map { |g| Array(g["hooks"]).map { |h| h["command"] } }
+      missing.concat(want - got)
+    end
+
+    if missing.empty?
+      check(
+        category: "agent_registration", name: "codex_hooks_registered", status: "pass",
+        message: "Codex hooks registered in hooks.json"
+      )
+    else
+      check(
+        category: "agent_registration", name: "codex_hooks_registered", status: "fail",
+        message: "Codex hooks.json missing #{missing.size} command(s)",
+        details: missing,
+        fixable: true, fix_hint: "Re-run the Plastic installer with --codex"
+      )
+    end
+  end
+
+  # config.toml advisory (intent 102, Decision 2, R2): READ ONLY. Warns on the two
+  # documented footguns (hooks disabled, sandbox read-only); never writes, and
+  # returns nil (no check emitted) when config.toml is absent or carries neither.
+  def codex_config_toml_advisory_check(config)
+    config_toml = File.join(config[:home_dir], "config.toml")
+    return nil unless File.exist?(config_toml)
+
+    toml = File.read(config_toml) rescue ""
+    warns = []
+    # guide Part 3: `codex_hooks` is a deprecated alias for `[features] hooks`; catch both.
+    warns << "hooks are disabled ([features] hooks = false); Plastic gates will not fire" if toml.match?(/^\s*(?:codex_)?hooks\s*=\s*false/)
+    warns << "sandbox_mode = \"read-only\"; apply_patch writes (and gates) cannot run" if toml.match?(/^\s*sandbox_mode\s*=\s*["']read-only["']/)
+    return nil if warns.empty?
+
+    check(
+      category: "agent_registration", name: "codex_config_advisory", status: "warn",
+      message: warns.join("; "),
+      fixable: false,
+      fix_hint: "Set [features] hooks = true and sandbox_mode = \"workspace-write\" in ~/.codex/config.toml"
+    )
+  end
+
   # --- Check category 4: Core files ---
 
   def check_core_files(agent_key)

package/scripts/lib/agent_models.rb

@@ -21,6 +21,18 @@ module AgentModels
     "plastic-intent-discovery" => "sonnet"
   }.freeze
 
+  # Codex reasoning-effort per tier alias (intent 102a). model_reasoning_effort is a
+  # depth-of-thinking dial independent of model selection (181 line 317-318), so mapping
+  # the tier here never encodes a rotting Codex model id (116 D1). opus is the deepest
+  # reasoning tier -> the deepest generally-safe effort (high, not the model-dependent
+  # xhigh); sonnet the mid execution tier -> medium; haiku the lightest -> low. minimal is
+  # unused.
+  EFFORT_BY_ALIAS = {
+    "opus" => "high",
+    "sonnet" => "medium",
+    "haiku" => "low"
+  }.freeze
+
   module_function
 
   # Pull the `agents.models` sub-hash out of a loaded config hash, tolerating a
@@ -40,4 +52,10 @@ module AgentModels
   def override_map(project_config: {}, global_config: {})
     models_section(global_config).merge(models_section(project_config))
   end
+
+  # The model_reasoning_effort for a Plastic tier alias, or nil for any value that is not
+  # one of the three shipped aliases (the caller treats nil as a literal Codex model id).
+  def effort_for(value)
+    EFFORT_BY_ALIAS[value.to_s]
+  end
 end

package/scripts/lib/apply_patch_envelope.rb

@@ -0,0 +1,76 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Parses a Codex `apply_patch` command envelope into an ordered list of file
+# operations. Codex delivers file mutations as a V4A diff envelope in
+# tool_input.command, not a clean file_path+content pair, and ONE apply_patch call
+# can bundle several files. This is the single translation the Codex gate shims
+# need; the Ruby gate/savepoint cores stay payload-agnostic behind it.
+#
+# Guide-settled shapes consumed here (intent 102, Decision 0, owner ruling):
+# [guide Part 3] the `~/.codex/hooks.json` registration schema (consumed by
+# HookRegistry.codex_hooks_json and merge_codex_hooks, not this file). [guide
+# Part 4] the hook stdin schema, including `tool_input.command` as the carrier of
+# the apply_patch envelope text (consumed by scripts/codex-hook).
+#
+# Residual gap (in neither the guide nor 181, per Decision 14): the apply_patch
+# V4A envelope INNER grammar parsed below (`*** Begin/End Patch`, `*** Add/Update/
+# Delete File:`, `*** Move to:`, `+`/`-`/context lines) is not primary-sourced.
+# There is no live Codex to verify it against (the owner has none installed), so
+# this parser is built to the best-known public V4A shape and FAILS OPEN on
+# anything else. Returns [] and warns on any missing or unparseable envelope:
+# gates fail OPEN (orchestrator-locks fail-open rule). The PostToolUse gate-check
+# artifact backstop re-validates the intent file after the write, so a fail-open
+# create-gate is still netted. A real Codex run after delivery is the only future
+# check on this residual.
+module ApplyPatchEnvelope
+  module_function
+
+  Op = Struct.new(:op, :path, :added_content, keyword_init: true)
+
+  BEGIN_MARK = "*** Begin Patch"
+  END_MARK   = "*** End Patch"
+  ADD_RE     = /\A\*\*\* Add File: (.+)\z/
+  UPDATE_RE  = /\A\*\*\* Update File: (.+)\z/
+  DELETE_RE  = /\A\*\*\* Delete File: (.+)\z/
+  MOVE_RE    = /\A\*\*\* Move to: (.+)\z/
+
+  # command may be a String or (per Step 1) an Array of argv; normalize to the
+  # patch text by scanning for the Begin/End markers regardless of wrapping.
+  def parse(command)
+    text = command.is_a?(Array) ? command.join("\n") : command.to_s
+    b = text.index(BEGIN_MARK)
+    e = text.index(END_MARK)
+    return warn_empty("no Begin/End Patch markers") if b.nil? || e.nil? || e < b
+
+    body = text[(b + BEGIN_MARK.length)...e]
+    ops = []
+    current = nil
+    body.each_line do |raw|
+      line = raw.chomp
+      if (m = ADD_RE.match(line))
+        current = Op.new(op: :add, path: m[1].strip, added_content: +"")
+        ops << current
+      elsif (m = UPDATE_RE.match(line))
+        current = Op.new(op: :update, path: m[1].strip, added_content: +"")
+        ops << current
+      elsif (m = DELETE_RE.match(line))
+        current = Op.new(op: :delete, path: m[1].strip, added_content: nil)
+        ops << current
+      elsif (m = MOVE_RE.match(line)) && current
+        current.path = m[1].strip # rename target becomes the effective path
+      elsif current && current.added_content && line.start_with?("+")
+        current.added_content << line[1..].to_s << "\n"
+      end
+      # context (' '), removed ('-'), and '@@' lines are ignored for added_content
+    end
+    ops
+  rescue StandardError => e
+    warn_empty("parse error: #{e.message}")
+  end
+
+  def warn_empty(reason)
+    $stderr.puts "plastic apply_patch parse: #{reason}; gate fails open"
+    []
+  end
+end

package/scripts/lib/hook_registry.rb

@@ -75,6 +75,38 @@ module HookRegistry
     }
   end
 
+  # Codex registration (~/.codex/hooks.json, intent 102). Derived from `events`:
+  # the file-mutation PreToolUse gate/savepoint hooks collapse from Claude's
+  # multi-tool matchers onto Codex's single apply_patch tool (181 F4: apply_patch
+  # is Codex's sole file-mutation tool; tool_name always reports apply_patch), plus
+  # the PostToolUse gate-check. Command invokes the codex-hook dispatcher with the
+  # gate name. Guide-settled shape [guide Part 3]: top-level {"hooks":{<Event>:
+  # [{"matcher","hooks":[{"type":"command","command","statusMessage"}]}]}},
+  # identical to Claude's shape, string command. Single source of truth (108 D7):
+  # any drift from `events` is a bug, pinned by test.
+  CODEX_PRE_HOOKS  = %w[code-gate lock-gate savepoint-pre create-gate].freeze
+  CODEX_POST_HOOKS = %w[gate-check].freeze
+
+  def codex_hooks_json(dispatcher_path:)
+    # name => statusMessage, straight from the single `events` source (A8): the
+    # guide Part 3 hooks.json format carries a per-hook statusMessage, so emit it.
+    status_by_name = events.values.flatten.flat_map { |g| g["hooks"] }
+                           .each_with_object({}) { |h, m| m[h["name"]] = h["status"] }
+    cmd = ->(name) {
+      { "type" => "command",
+        "command" => "\"#{dispatcher_path}\" #{name}",
+        "statusMessage" => status_by_name[name].to_s }
+    }
+    # Preserve the order these hook names appear across the PreToolUse groups in `events`.
+    pre_order = events["PreToolUse"].flat_map { |g| g["hooks"].map { |h| h["name"] } }
+    pre = (pre_order & CODEX_PRE_HOOKS).map { |n| cmd.call(n) }
+    post = CODEX_POST_HOOKS.map { |n| cmd.call(n) }
+    {
+      "PreToolUse"  => [{ "matcher" => "apply_patch", "hooks" => pre }],
+      "PostToolUse" => [{ "matcher" => "apply_patch", "hooks" => post }],
+    }
+  end
+
   # The settings.json shape merge_claude_hooks expects: single-group events map
   # to a Hash, multi-group events to an Array (the merge loop handles both).
   def claude_settings_hooks(hook_dir:)

package/scripts/lib/installer_core.rb

@@ -18,10 +18,39 @@ class InstallerCore
 
   DEFAULT_AGENTS = [
     { key: "claude", name: "Claude Code", dir: File.join(Dir.home, ".claude"), flag: "--claude" },
-    { key: "codex", name: "Codex CLI", dir: File.join(Dir.home, ".agents"), flag: "--codex" },
+    { key: "codex", name: "Codex CLI", dir: File.join(Dir.home, ".agents"),
+      home_dir: File.join(Dir.home, ".codex"), flag: "--codex" },
     { key: "hermes", name: "Hermes", dir: File.join(Dir.home, ".hermes"), flag: "--hermes" },
   ].freeze
 
+  # Codex AGENTS.md marked-section markers (single source of truth; doctor.rb
+  # matches these literals structurally, so keep the two in sync by hand).
+  CODEX_SECTION_BEGIN_PREFIX = "<!-- BEGIN PLASTIC INTEGRATION"
+  CODEX_SECTION_END = "<!-- END PLASTIC INTEGRATION -->"
+
+  # Regex matching exactly one managed section (BEGIN line .. END line), non-greedy.
+  CODEX_SECTION_RE = /^<!-- BEGIN PLASTIC INTEGRATION.*?-->\n.*?\n<!-- END PLASTIC INTEGRATION -->\n?/m
+
+  # Curated essentials plus a pointer to ~/.plastic/PLASTIC.md, injected into
+  # ~/.codex/AGENTS.md. Not a slice of PLASTIC.md (which is already over the 32 KiB
+  # AGENTS.md merge cap on its own), so it never drifts and carries no maintenance fork.
+  CODEX_AGENTS_MD_BODY = <<~MD.freeze
+    Plastic is installed for this agent. Plastic is intent-driven state management: all
+    work flows through an intent, moved through What, Why, How, then Exec. Do not jump
+    straight to code.
+
+    Standing rules:
+    - The full conventions live in ~/.plastic/PLASTIC.md. Read it and follow it exactly.
+      It is generated and overwritten on Plastic updates, so never edit it.
+    - Operational procedures are installed as skills under ~/.agents/skills/ (each
+      plastic-<name>/SKILL.md). Use them for the lifecycle work they describe.
+    - Intents, specs, plans, checklists, and outcomes live under ~/.plastic/, never in
+      the project tree.
+
+    This section is managed by the Plastic installer. It is replaced on update and removed
+    on uninstall. Do not edit anything between the BEGIN and END markers.
+  MD
+
   attr_reader :package_root, :plastic_home, :version, :agents
 
   def initialize(package_root:, plastic_home: DEFAULT_PLASTIC_HOME, version: nil, agents: DEFAULT_AGENTS)
@@ -278,6 +307,8 @@ class InstallerCore
       "scripts/new-intent" => "scripts/new-intent",
       "scripts/end-intent" => "scripts/end-intent",
       "scripts/hook-create-gate" => "scripts/hook-create-gate",
+      "scripts/lib/apply_patch_envelope.rb" => "scripts/lib/apply_patch_envelope.rb",
+      "scripts/codex-hook" => "scripts/codex-hook",
       "templates/intent.md" => "templates/intent.md",
       "templates/spec.md" => "templates/spec.md",
       "templates/plan.md" => "templates/plan.md",
@@ -465,12 +496,146 @@ class InstallerCore
     installed = []
     skills_source = File.join(package_root, "skills")
     installed += install_skills_flat(skills_source, File.join(config[:dir], "skills")) if File.directory?(skills_source)
-    installed += install_agents(File.join(config[:dir], "agents"), models: agent_model_overrides)
+    installed += generate_codex_agents(File.join(config[:home_dir], "agents"), models: agent_model_overrides)
+
+    # Instruction injection (L1): Plastic standing conventions into ~/.codex/AGENTS.md.
+    # Partial-ownership file, so it is NOT manifest-tracked (stripped surgically on uninstall).
+    FileUtils.mkdir_p(config[:home_dir])
+    inject_codex_agents_md(File.join(config[:home_dir], "AGENTS.md"))
+
+    # L3 hooks (intent 102): register into ~/.codex/hooks.json (user scope, defeats the
+    # worktree bug). Partial-ownership file, so it is merged and NOT manifest-tracked
+    # (stripped surgically on uninstall), same treatment as AGENTS.md.
+    merge_codex_hooks(File.join(config[:home_dir], "hooks.json"))
 
     write_manifest(installed, File.join(config[:dir], "plastic-manifest.json"))
     { agent: config[:name], success: true, files: installed.size }
   end
 
+  # --- Codex agent TOML generation (intent 102a) ---
+  #
+  # Codex reads standalone TOML agent files at ~/.codex/agents/*.toml (config[:home_dir]),
+  # never the ~/.agents/agents/*.md copy the shared install_agents writes (that root is
+  # the cross-tool skills standard, not an agents root). The codex leg therefore generates
+  # a whole-file, Plastic-owned .toml per repo agents/*.md instead of copying markdown.
+  # The returned paths append to `installed`, so they are manifest-tracked and pruned on
+  # uninstall by the manifest whole-file-delete path, exactly like ~/.claude/agents/*.md.
+  def generate_codex_agents(agents_root, models: {})
+    sources = Dir.glob(File.join(package_root, "agents", "*.md"))
+    return [] if sources.empty?
+
+    FileUtils.mkdir_p(agents_root)
+    sources.map do |src|
+      basename = File.basename(src, ".md")
+      dest = File.join(agents_root, "#{basename}.toml")
+      write_text_atomic(dest, render_codex_agent_toml(src, models[basename]))
+      dest
+    end
+  end
+
+  # Render one repo agents/*.md into a deterministic Codex agent TOML document. Fixed field
+  # order (name, description, one model field, developer_instructions) so regenerate is
+  # byte-identical (idempotency).
+  def render_codex_agent_toml(source_path, override)
+    front, body = split_frontmatter(File.read(source_path))
+    name = (front["name"] || File.basename(source_path, ".md")).to_s
+    description = (front["description"] || "").to_s
+    effective = (override && !override.to_s.empty? ? override : front["model"]).to_s
+
+    parts = []
+    parts << %(name = "#{toml_inline_escape(name)}")
+    parts << %(description = "#{toml_inline_escape(description)}")
+    parts << codex_model_fields(effective)
+    parts << "developer_instructions = \"\"\"\n#{toml_ml_escape(body.strip)}\n\"\"\""
+    parts.reject(&:empty?).join("\n") + "\n"
+  end
+
+  # Split a Plastic agent .md into [frontmatter_hash, body]. Tolerant: a file with no
+  # frontmatter yields [{}, whole content].
+  def split_frontmatter(content)
+    if content =~ /\A---\s*\n(.*?)\n---\s*\n?(.*)\z/m
+      front = YAML.safe_load($1) rescue {}
+      front = {} unless front.is_a?(Hash)
+      [front, $2]
+    else
+      [{}, content]
+    end
+  end
+
+  # The single model-selection line. A known tier alias (opus/sonnet/haiku) emits
+  # model_reasoning_effort only; any other non-empty value is a literal Codex model id
+  # emitted verbatim as `model`. Empty -> no line (the agent inherits the session default).
+  def codex_model_fields(effective)
+    return "" if effective.nil? || effective.to_s.empty?
+    effort = AgentModels.effort_for(effective)
+    if effort
+      %(model_reasoning_effort = "#{effort}")
+    else
+      %(model = "#{toml_inline_escape(effective.to_s)}")
+    end
+  end
+
+  # Escape arbitrary text for a TOML multi-line basic string ("""..."""). Order matters:
+  # normalize line endings, escape backslash FIRST (so introduced escapes are not
+  # re-escaped), then EVERY double-quote (which alone prevents any triple-quote delimiter
+  # collision), then C0 control chars other than tab/newline.
+  def toml_ml_escape(str)
+    s = str.to_s.gsub(/\r\n?/, "\n")
+    s = s.gsub("\\") { "\\\\" }
+    s = s.gsub('"') { '\\"' }
+    s.gsub(/[\x00-\x08\x0b\x0c\x0e-\x1f]/) { |c| format('\u%04X', c.ord) }
+  end
+
+  # Escape text for a single-line TOML basic string ("..."). Collapse any newline to a
+  # space (single-line context), then the same backslash/quote/control escapes.
+  def toml_inline_escape(str)
+    s = str.to_s.gsub(/\s*\r?\n\s*/, " ").strip
+    s = s.gsub("\\") { "\\\\" }
+    s = s.gsub('"') { '\\"' }
+    s.gsub(/[\x00-\x08\x0b\x0c\x0e-\x1f]/) { |c| format('\u%04X', c.ord) }
+  end
+
+  def codex_dispatcher_path
+    File.join(plastic_home, "scripts", "codex-hook")
+  end
+
+  # ~/.codex/hooks.json merge (intent 102). Guide-settled shape [guide Part 3]:
+  # top-level {"hooks": {<Event>: [...]}}, identical to Claude's settings.json
+  # hooks shape, so this mirrors merge_claude_hooks against a different file and
+  # a different purge predicate (the dispatcher command contains "codex-hook",
+  # not the "plastic-" substring merge_claude_hooks matches, since the path is
+  # "~/.plastic/scripts/codex-hook", not "~/.claude/hooks/plastic-<name>").
+  def merge_codex_hooks(hooks_json_path)
+    data = read_json_safe(hooks_json_path) || {}
+    hooks = data["hooks"] ||= {}
+    purge_stale_codex_hooks(hooks)
+    plastic = HookRegistry.codex_hooks_json(dispatcher_path: codex_dispatcher_path)
+    plastic.each do |event, groups|
+      hooks[event] ||= []
+      Array(groups).each { |g| hooks[event] << g }
+    end
+    write_json_atomic(hooks_json_path, data)
+  end
+
+  def purge_stale_codex_hooks(hooks)
+    codex_cmd = ->(cmd) { cmd.to_s.include?("codex-hook") }
+
+    hooks.each do |event, groups|
+      next unless groups.is_a?(Array)
+
+      hooks[event] = groups.map do |group|
+        if group.is_a?(Hash) && group["hooks"].is_a?(Array)
+          group["hooks"].reject! { |h| codex_cmd.call(h["command"]) }
+          group unless group["hooks"].empty?
+        elsif group.is_a?(Hash) && group["command"]
+          codex_cmd.call(group["command"]) ? nil : group
+        else
+          group
+        end
+      end.compact
+    end
+  end
+
   def install_hermes(config, force)
     installed = []
     skills_source = File.join(package_root, "skills")
@@ -691,6 +856,77 @@ class InstallerCore
     end
   end
 
+  # --- Codex AGENTS.md marked-section injection (22a/Beads pattern) ---
+  # New primitive: markdown marked-section merge, the analog of merge_claude_hooks'
+  # JSON read-modify-write for a partial-ownership text file. Three states
+  # (create/append/replace), a body freshness hash in the BEGIN marker, atomic
+  # writes, and the 22a safety rule: never write when the existing section can't
+  # be parsed (a BEGIN marker with no matching END).
+
+  # Atomic text writer, mirrors write_json_atomic.
+  def write_text_atomic(path, content)
+    tmp = "#{path}.plastic-tmp.#{Process.pid}"
+    File.write(tmp, content)
+    File.rename(tmp, path)
+  rescue => e
+    File.delete(tmp) if tmp && File.exist?(tmp)
+    raise e
+  end
+
+  def codex_section(body: CODEX_AGENTS_MD_BODY)
+    hash = Digest::SHA256.hexdigest(body)[0, 12]
+    "#{CODEX_SECTION_BEGIN_PREFIX} hash:#{hash} -->\n#{body.strip}\n#{CODEX_SECTION_END}\n"
+  end
+
+  # Returns :created / :appended / :replaced / :refused. Never raises on a normal user file.
+  def inject_codex_agents_md(path, body: CODEX_AGENTS_MD_BODY)
+    section = codex_section(body: body)
+
+    unless File.exist?(path)
+      FileUtils.mkdir_p(File.dirname(path))
+      write_text_atomic(path, section)
+      return :created
+    end
+
+    content = File.read(path)
+    has_begin = content.include?(CODEX_SECTION_BEGIN_PREFIX)
+    has_end = content.include?(CODEX_SECTION_END)
+
+    # 22a safety rule: never write if the existing section cannot be parsed.
+    return :refused if has_begin && !has_end
+
+    if has_begin
+      write_text_atomic(path, content.sub(CODEX_SECTION_RE, section))
+      :replaced
+    else
+      base = content.end_with?("\n") ? content : content + "\n"
+      write_text_atomic(path, base + "\n" + section)
+      :appended
+    end
+  end
+
+  # Remove exactly Plastic's managed section from a user-owned AGENTS.md. Preserve all other
+  # content. Delete the file only if Plastic created it and nothing else remains. Returns the
+  # path when it acted, nil on no-op. Mirrors remove_claude_hooks: dedicated surgical strip,
+  # never the manifest whole-file-delete path.
+  def strip_codex_section(path)
+    return nil unless File.exist?(path)
+    content = File.read(path)
+    return nil unless content.include?(CODEX_SECTION_BEGIN_PREFIX)
+
+    # Remove the section plus the single separator newline the append introduced, so a
+    # standard user file round-trips byte-identical.
+    stripped = content.sub(/\n?#{CODEX_SECTION_RE}/, "")
+
+    if stripped.strip.empty?
+      File.delete(path)                 # Plastic-created file: nothing else left
+    else
+      stripped = stripped.rstrip + "\n" # normalize trailing whitespace we may have left
+      write_text_atomic(path, stripped)
+    end
+    path
+  end
+
   # --- Uninstall ---
 
   def handle_uninstall(uninstall_agents)
@@ -765,6 +1001,19 @@ class InstallerCore
       removed.concat(migrate_legacy_plugin(config[:dir]))
     end
 
+    # Codex: surgically strip Plastic's marked section from the user-owned AGENTS.md
+    # (dedicated pair, never the manifest whole-file-delete path above), plus the
+    # Plastic entries from hooks.json (intent 102).
+    if key == "codex"
+      agents_md = File.join(config[:home_dir], "AGENTS.md")
+      stripped = strip_codex_section(agents_md)
+      removed << stripped if stripped
+
+      hooks_json = File.join(config[:home_dir], "hooks.json")
+      hooks_removed = remove_codex_hooks(hooks_json)
+      removed << hooks_removed if hooks_removed
+    end
+
     { success: true, files: removed.size, removed: removed }
   end
 
@@ -807,6 +1056,38 @@ class InstallerCore
     write_json_atomic(settings_path, settings)
   end
 
+  # Remove exactly Plastic's entries from ~/.codex/hooks.json (intent 102), mirrors
+  # remove_claude_hooks against the Codex file/purge predicate. Returns the path
+  # when it acted (rewritten or deleted), nil on no-op, mirroring strip_codex_section's
+  # convention so the caller only records an actual change.
+  def remove_codex_hooks(hooks_json_path)
+    data = read_json_safe(hooks_json_path)
+    return nil unless data && data["hooks"]
+
+    before = JSON.generate(data)
+
+    data["hooks"].each do |event, groups|
+      next unless groups.is_a?(Array)
+
+      data["hooks"][event] = groups.map do |g|
+        next g unless g.is_a?(Hash) && Array(g["hooks"]).is_a?(Array)
+
+        g["hooks"] = Array(g["hooks"]).reject { |h| h["command"].to_s.include?("codex-hook") }
+        g["hooks"].empty? ? nil : g
+      end.compact
+    end
+    data["hooks"].delete_if { |_, v| v.is_a?(Array) && v.empty? }
+
+    return nil if JSON.generate(data) == before # nothing to change: true no-op
+
+    if data["hooks"].empty? && data.keys == ["hooks"]
+      File.delete(hooks_json_path) # Plastic-created and now empty: remove
+    else
+      write_json_atomic(hooks_json_path, data)
+    end
+    hooks_json_path
+  end
+
   # --- Utilities ---
 
   def agent_config(key)

package/skills/roadmap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plastic-roadmap
-description: Use when the user wants to plan a delivery batch, order waves of intents, ship a batch of tickets in one go, track a named collection of intents toward a goal, or asks for a "roadmap". Creates and maintains a roadmap file, a delivery-side collection of intents (the counterpart to a release), separate from INDEX.md status tracking.
+description: Use when the user wants to plan a delivery batch, order waves of intents, ship a batch of intents in one go, track a named collection of intents toward a goal, or asks for a "roadmap". Creates and maintains a roadmap file, a delivery-side collection of intents (the counterpart to a release), separate from INDEX.md status tracking.
 user-invocable: true
 ---
 

package/skills/roadmap-continuing/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Use when the user wants to continue or resume a roadmap, pick up a mid-flight delivery batch,
   asks "where is the roadmap", or wants to resume the wave that was shipping, including an
   indirect ask that never names a roadmap directly (for example "where did that batch of
-  tickets land"). This is the roadmap route of plastic-continuing: it finds the tier's
+  intents land"). This is the roadmap route of plastic-continuing: it finds the tier's
   mid-flight roadmap, presents its state, then asks how to proceed exactly once.
 user-invocable: true
 ---

package/skills/roadmap-continuing/evals/evals.json

@@ -26,7 +26,7 @@
     },
     {
       "id": 3, "scope": "triggering", "set": "validation",
-      "prompt": "where did that batch of tickets land",
+      "prompt": "where did that batch of intents land",
       "expected_output": "Activates plastic-roadmap-continuing (indirect trigger: a roadmap-resume request that never names 'roadmap' or 'continue').",
       "files": [],
       "assertions": [