@zalom/plastic 1.1.5 → 1.3.0

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/install.rb

@@ -57,6 +57,7 @@ class Install < InstallerCore
 
     distribute(mode)
     bootstrap if fresh
+    apply_config_flags(argv)
 
     results = selected.map { |key| install_for_agent(key, force, argv: argv, input: input, reinstall: reinstall) }
 
@@ -158,6 +159,13 @@ class Install < InstallerCore
         --statusline VALUE   keep or plastic. If an existing statusline is found, this
                              skips the interactive prompt. Interactive sessions ask by
                              default; non-interactive sessions default to keep.
+        --no-advisor         Skip installing both advisor agents and the agent-advisor
+                             skill (advisor.enabled: false)
+        --advisor VALUE      Which advisor agent is the default: an agent name, or the
+                             shorthand "real" (plastic-advisor) or "faux"
+                             (plastic-faux-advisor). Writes advisor.claude.default. Left
+                             unset, the agent-advisor skill falls back to
+                             plastic-faux-advisor at consult time.
         -h, --help           Show this help
 
       Notes:

package/scripts/lib/agent_models.rb

@@ -21,23 +21,68 @@ module AgentModels
     "plastic-intent-discovery" => "sonnet"
   }.freeze
 
+  # The two advisor agents (intent 185 final design): plastic-advisor (the real
+  # advisor, ships `model: fable`) and plastic-faux-advisor (the imitation
+  # advisor, an ordinary model carrying the same reasoning discipline inline,
+  # ships `model: opus`). Both are shipped DEFAULTS in frontmatter, never a
+  # hard-wired identity: agents.models.claude.<name> (or the legacy flat form)
+  # overrides either one through the same install-time frontmatter rewrite
+  # every agent override uses. Neither is a lifecycle-stage role: never
+  # dispatched by the auto pipeline, not part of TIER_DEFAULTS. Claude-only for
+  # this release (generate_codex_agents skips both by name; the Codex advisor
+  # case is intent 186, not a permanent exclusion).
+  CONSULTATION_AGENTS = %w[plastic-advisor plastic-faux-advisor].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
-  # missing or malformed shape. Returns a plain { basename => model } hash.
-  def models_section(config)
+  # Pull { basename => model } out of a loaded config hash's `agents.models`
+  # section, scoped to `harness` ("claude" or "codex"), tolerating a missing or
+  # malformed shape. `agents.models` can mix two shapes: legacy FLAT scalar
+  # entries (agents.models.plastic-executor: sonnet), honored as the claude
+  # harness only, and harness-scoped sub-hashes (agents.models.claude.*,
+  # agents.models.codex.*). Nested wins over flat for the same agent on the
+  # claude harness; a non-claude harness reads ONLY its own nested sub-hash,
+  # never the flat entries, so a literal model id written under the flat form
+  # (or agents.models.claude.*) can never leak into another harness's config.
+  def models_section(config, harness: "claude")
     return {} unless config.is_a?(Hash)
     agents = config["agents"]
     return {} unless agents.is_a?(Hash)
     section = agents["models"]
-    section.is_a?(Hash) ? section : {}
+    return {} unless section.is_a?(Hash)
+
+    nested = section[harness]
+    nested = nested.is_a?(Hash) ? nested : {}
+    return nested unless harness == "claude"
+
+    flat = section.reject { |_key, value| value.is_a?(Hash) }
+    flat.merge(nested)
   end
 
   # Override map for the installer: global overrides overlaid by project
-  # overrides (project wins). Defaults are intentionally excluded. Unknown agent
-  # keys are carried through as-is; install_agents simply never matches them to a
-  # copied file, so they are ignored without raising.
-  def override_map(project_config: {}, global_config: {})
-    models_section(global_config).merge(models_section(project_config))
+  # overrides (project wins), scoped to `harness`. Defaults are intentionally
+  # excluded. Unknown agent keys are carried through as-is; install_agents
+  # simply never matches them to a copied file, so they are ignored without
+  # raising.
+  def override_map(project_config: {}, global_config: {}, harness: "claude")
+    models_section(global_config, harness: harness).merge(models_section(project_config, harness: harness))
+  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:)