@zalom/plastic 1.4.0 → 1.5.0

package/scripts/doctor.rb

@@ -52,18 +52,14 @@ class Doctor
   # never drift.
   LEGACY_BOOKEND_AMNESTY = LegacyBookendAmnesty::LIST
 
-  CLAUDE_HOOK_SCRIPTS = %w[
-    plastic-session-start
-    plastic-check-update
-    plastic-savepoint
-    plastic-gate-check
-    plastic-continue
-    plastic-future-intent-check
-    plastic-qmd-search
-  ].freeze
-
   CLAUDE_HOOK_EVENTS = %w[SessionStart PreCompact PostToolUse UserPromptSubmit].freeze
 
+  # Launchers the installer places in the agent's hooks dir that are NOT hooks
+  # (intent 204): plastic-statusline is the settings["statusLine"] command, wired
+  # outside HookRegistry.events entirely, so it must be excluded from the
+  # orphan-launcher scan below or a correct install would report a false orphan.
+  CLAUDE_NON_HOOK_LAUNCHERS = %w[plastic-statusline].freeze
+
   REQUIRED_SCRIPTS = %w[
     folgezettel-id
     read-config
@@ -815,7 +811,11 @@ class Doctor
       "it PRESERVES any line unbacked by frontmatter that still resolves to a real intent " \
       "(reported as an orphan candidate, never silently deleted); add the missing " \
       "sources/chain edge if the relationship is real, or pass --drop-unbacked-links to " \
-      "delete an orphan candidate deliberately."
+      "delete an orphan candidate deliberately. Prefer `ruby scripts/maintenance-run --tool " \
+      "project-links --intent <id> --apply` over running project-links directly: it detects " \
+      "(never acquires) the target's delivery lock, requires a clean store working tree, and " \
+      "commits the scoped change plus its revisions.md receipt as one merged operation " \
+      "(PLASTIC.md > WORK vs MAINTENANCE)."
     )
   end
 
@@ -1003,13 +1003,17 @@ class Doctor
     checks = []
     hooks_dir = File.join(agent_dir, "hooks")
 
+    # Derived from HookRegistry.events (intent 204), not a hand-kept list, so
+    # every registered hook (all 15, including the enforcement gates) is checked.
+    expected_launchers = HookRegistry.claude_launcher_names
+
     # hooks_exist
-    missing_hooks = CLAUDE_HOOK_SCRIPTS.reject { |h| File.exist?(File.join(hooks_dir, h)) }
+    missing_hooks = expected_launchers.reject { |h| File.exist?(File.join(hooks_dir, h)) }
 
     if missing_hooks.empty?
       checks << check(
         category: "agent_registration", name: "hooks_exist", status: "pass",
-        message: "All #{CLAUDE_HOOK_SCRIPTS.size} expected hook scripts exist"
+        message: "All #{expected_launchers.size} expected hook scripts exist"
       )
     else
       checks << check(
@@ -1021,7 +1025,7 @@ class Doctor
     end
 
     # hooks_executable
-    existing_hooks = CLAUDE_HOOK_SCRIPTS
+    existing_hooks = expected_launchers
       .map { |h| File.join(hooks_dir, h) }
       .select { |p| File.exist?(p) }
 
@@ -1041,6 +1045,29 @@ class Doctor
       )
     end
 
+    # hooks_no_orphans: the mirror of hooks_exist. A plastic-* launcher on disk
+    # that HookRegistry does not know about is dead code the next reader would
+    # trust as live (the same drift class as a missing launcher, just facing
+    # the other way). plastic-statusline is a legitimate non-hook installer
+    # artifact (see CLAUDE_NON_HOOK_LAUNCHERS) and is excluded here.
+    present_launchers = Dir.glob(File.join(hooks_dir, "plastic-*")).map { |p| File.basename(p) }
+    orphans = (present_launchers - expected_launchers - CLAUDE_NON_HOOK_LAUNCHERS).sort
+
+    if orphans.empty?
+      checks << check(
+        category: "agent_registration", name: "hooks_no_orphans", status: "pass",
+        message: "No orphaned hook launchers in #{tilde(hooks_dir)}"
+      )
+    else
+      checks << check(
+        category: "agent_registration", name: "hooks_no_orphans", status: "warn",
+        message: "#{orphans.size} hook launcher(s) on disk are not registered in HookRegistry",
+        details: orphans.map { |h| "#{tilde(hooks_dir)}/#{h}" },
+        fixable: true,
+        fix_hint: "Re-run the Plastic installer: npx @zalom/plastic@latest --claude (prunes stale launchers)"
+      )
+    end
+
     # hooks_registered — settings.json has Plastic hooks for required events
     settings_path = File.join(agent_dir, "settings.json")
     settings = read_json_safe(settings_path)
@@ -1268,12 +1295,35 @@ class Doctor
       end
     end
 
-    checks << codex_hooks_registered_check(config)
+    hooks_check = codex_hooks_registered_check(config)
+    checks << hooks_check
+    checks << codex_hooks_implemented_check(config)
+    checks << codex_hook_trust_advisory_check if hooks_check[:status] == "pass"
     codex_config_toml_advisory_check(config).tap { |c| checks << c if c }
 
     checks
   end
 
+  # Hooks being REGISTERED (hooks.json content matches HookRegistry) is not
+  # the same as hooks being TRUSTED: Codex gates every non-managed hook
+  # command behind a human /hooks review, keyed by the command's current
+  # hash, so a release that changes a hook command re-arms the review
+  # (intent 198, Decision D2). Whether Codex persists a queryable trust
+  # record anywhere under ~/.codex is undocumented and unverified, so this
+  # can never be a real pass or fail on trust state; it is an advisory that
+  # always names the /hooks step, and it fires only once hooks are actually
+  # registered (an unregistered hook is already reported by
+  # codex_hooks_registered_check, so reminding about trust on top of that
+  # would be noise, not signal).
+  def codex_hook_trust_advisory_check
+    check(
+      category: "agent_registration", name: "codex_hooks_trust", status: "warn",
+      message: "Open Codex, run /hooks, and trust the Plastic hook definitions. " \
+               "Codex re-arms this review whenever a hook's command changes.",
+      fixable: false
+    )
+  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
@@ -1315,6 +1365,15 @@ class Doctor
     has_name && has_desc && !di.nil? && !balanced.nil?
   end
 
+  # Plain string extraction of the single model-selection line a generated
+  # Codex agent TOML carries (model_reasoning_effort for a tier alias, model
+  # for a literal override id; codex_model_fields never emits both). No TOML
+  # parser dependency, mirroring codex_agent_toml_well_formed? above.
+  def codex_agent_toml_model_value(content)
+    m = content.match(/^model_reasoning_effort\s*=\s*"([^"]*)"/) || content.match(/^model\s*=\s*"([^"]*)"/)
+    m && m[1]
+  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
@@ -1356,6 +1415,124 @@ class Doctor
     end
   end
 
+  # codex_hooks_implemented (intent 200): codex_hooks_registered_check above proves
+  # hooks.json content matches what HookRegistry would emit; both sides of THAT
+  # comparison come from the registry, so a pass only proves the registry agrees
+  # with itself. It never looks at the actual dispatcher, so it cannot see a
+  # registered gate with no real branch there (links-gate shipped exactly this way,
+  # dead, in v1.4.0/intent 192, invisible to doctor and the suite until 198 found it
+  # by hand), or a dispatcher branch nobody registers (bash-gate's shape, intent
+  # 203, in the opposite direction). This check closes both directions at once.
+
+  # The Codex gate names HookRegistry actually registers: the six apply_patch-gated
+  # names (CODEX_PRE_HOOKS + CODEX_POST_HOOKS), the two Bash-matcher shell gates
+  # (CODEX_BASH_HOOKS), and the live-state hook names Codex inherits whole from
+  # `events` (CODEX_LIVE_STATE_EVENTS). No parsing needed: these are HookRegistry's
+  # own Ruby constants.
+  def codex_registry_gate_names
+    live_state = HookRegistry::CODEX_LIVE_STATE_EVENTS.flat_map do |event|
+      HookRegistry.events[event].flat_map { |g| g["hooks"].map { |h| h["name"] } }
+    end
+    (HookRegistry::CODEX_PRE_HOOKS + HookRegistry::CODEX_POST_HOOKS +
+     HookRegistry::CODEX_BASH_HOOKS + live_state).uniq
+  end
+
+  # Source-text extraction of scripts/codex-hook's supported gate names (D3): the
+  # dispatcher is an executable script with real top-level side effects (it reads
+  # $stdin and may exit), so it can never be required or executed to introspect it,
+  # only read as plain text, mirroring codex_agent_toml_well_formed? above. Pulls
+  # gate names from the STATE_HOOKS and SHELL_HOOKS %w[] literals, plus the `when
+  # "<name>"` labels of the top-level `case gate` statement (stopping at its
+  # trailing `else`). Line-shape dependent, not AST-safe, disclosed as such in
+  # docs; the healthy-install pass test against the REAL dispatcher is what proves
+  # this shape still holds.
+  #
+  # SELF-CHECKING: returns nil, never [], when nothing recognizable is found. A
+  # reshaped dispatcher (combined `when "a", "b"` arms, a multi-line array, a
+  # Hash-dispatch rewrite) would otherwise silently read as zero gate names, and a
+  # zero-gate dispatcher would make the diff below either flag every registered
+  # hook as "missing" or, worse, quietly under-report a real gap. A check that
+  # finds nothing and calls that healthy IS the exact disease this whole check
+  # exists to catch, one level up, so nil forces the caller (below) to fail loudly
+  # instead of reporting health it never actually verified.
+  def codex_dispatcher_gate_names(source)
+    names = []
+    %w[STATE_HOOKS SHELL_HOOKS].each do |const|
+      m = source.match(/^#{const}\s*=\s*%w\[([^\]]*)\]/)
+      names.concat(m[1].split(/\s+/)) if m
+    end
+
+    case_start = source.index(/^case gate\b/)
+    if case_start
+      case_body = source[case_start..-1]
+      else_idx = case_body.index(/^else\b/)
+      scanned = else_idx ? case_body[0...else_idx] : case_body
+      names.concat(scanned.scan(/^when\s+"([^"]+)"/).flatten)
+    end
+
+    names.uniq!
+    names.empty? ? nil : names
+  end
+
+  # The both-direction diff. Each mismatch becomes one detail line naming the
+  # hook, the direction, the harness ("Codex"), and the concrete runtime effect,
+  # never a generic "Codex hooks drift" message (D4).
+  def codex_hooks_implemented_check(config)
+    dispatcher_path = File.join(plastic_home, "scripts", "codex-hook")
+
+    unless File.exist?(dispatcher_path)
+      return check(
+        category: "agent_registration", name: "codex_hooks_implemented", status: "fail",
+        message: "scripts/codex-hook not found at #{tilde(dispatcher_path)}; cannot verify " \
+                 "the Codex hook registry and dispatcher agree",
+        fixable: true, fix_hint: "Re-run the Plastic installer with --codex"
+      )
+    end
+
+    dispatcher_names = codex_dispatcher_gate_names(File.read(dispatcher_path))
+
+    if dispatcher_names.nil?
+      return check(
+        category: "agent_registration", name: "codex_hooks_implemented", status: "fail",
+        message: "Could not read any gate names out of #{tilde(dispatcher_path)}: the " \
+                 "STATE_HOOKS/SHELL_HOOKS constants and the `case gate` statement no longer " \
+                 "match the shape this check expects, so the registry could not be checked " \
+                 "against the real dispatcher. This is exactly the silent-pass failure this " \
+                 "check exists to prevent; update codex_dispatcher_gate_names in doctor.rb " \
+                 "to the file's new shape.",
+        fixable: false
+      )
+    end
+
+    registry_names = codex_registry_gate_names
+    missing_dispatcher_branch = registry_names - dispatcher_names
+    dead_branch = dispatcher_names - registry_names
+
+    if missing_dispatcher_branch.empty? && dead_branch.empty?
+      return check(
+        category: "agent_registration", name: "codex_hooks_implemented", status: "pass",
+        message: "Every Codex-registered gate has a scripts/codex-hook branch, and every " \
+                 "dispatcher branch is registered"
+      )
+    end
+
+    details = missing_dispatcher_branch.map do |name|
+      "#{name} is registered in ~/.codex/hooks.json but scripts/codex-hook has no branch " \
+        "for it, so it always falls through to the fail-open else and always allows the write"
+    end
+    details += dead_branch.map do |name|
+      "#{name} has a branch in scripts/codex-hook but is not registered in HookRegistry for " \
+        "Codex, so it is dead code Codex never reaches"
+    end
+
+    check(
+      category: "agent_registration", name: "codex_hooks_implemented", status: "fail",
+      message: "Codex's hook registry and scripts/codex-hook disagree on #{details.size} gate(s)",
+      details: details,
+      fixable: false
+    )
+  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.
@@ -1547,6 +1724,8 @@ class Doctor
     agent_config = agents[agent_key]
     return [] unless agent_config
 
+    return check_agent_model_drift_codex(agent_config) if agent_key == "codex"
+
     agents_dir = File.join(agent_config[:dir], "agents")
     installed = Dir.glob(File.join(agents_dir, "plastic-*.md")).sort
 
@@ -1608,6 +1787,83 @@ class Doctor
     end
   end
 
+  # Codex leg of agent_model_drift (intent 198, Decision D4): the shared .md
+  # path above is structurally blind on Codex (codex agents are TOML under
+  # ~/.codex/agents/, never ~/.agents/agents/*.md), so it always passed on an
+  # empty glob without opening a single Codex file. This mirrors the same
+  # four buckets (sanctioned override, matches default, drifted,
+  # unclassified) against ~/.codex/agents/plastic-*.toml instead, reading
+  # model / model_reasoning_effort with the same plain string matching
+  # codex_agent_toml_well_formed? already uses (no TOML parser dependency).
+  # The expected value resolves through AgentModels::TIER_DEFAULTS mapped
+  # through AgentModels.effort_for, honoring the Codex-scoped
+  # agents.models.codex.<name> override precedence install_codex's own
+  # agent_model_overrides(harness: "codex") already applies.
+  # AgentModels::CONSULTATION_AGENTS need no special-case bucket here:
+  # generate_codex_agents already skips writing them for Codex entirely, so
+  # the glob below never finds them and there is nothing to classify.
+  def check_agent_model_drift_codex(agent_config)
+    agents_dir = File.join(agent_config[:home_dir], "agents")
+    installed = Dir.glob(File.join(agents_dir, "plastic-*.toml")).sort
+
+    if installed.empty?
+      return [check(
+        category: "core_files", name: "agent_model_drift", status: "pass",
+        message: "No installed plastic-* agent TOML files to check for model drift"
+      )]
+    end
+
+    global_config = load_yaml_safe(File.join(plastic_home, "config.yml")) || {}
+    overrides = AgentModels.override_map(project_config: {}, global_config: global_config, harness: "codex")
+
+    drifted = []
+    sanctioned = []
+    unclassified = []
+
+    installed.each do |path|
+      basename = File.basename(path, ".toml")
+      installed_value = codex_agent_toml_model_value(File.read(path))
+      override = overrides[basename]
+
+      if override
+        sanctioned << "#{basename}: toml=#{installed_value.inspect}, sanctioned override=#{override.inspect}"
+      elsif AgentModels::TIER_DEFAULTS.key?(basename)
+        expected_effort = AgentModels.effort_for(AgentModels::TIER_DEFAULTS[basename])
+        if installed_value != expected_effort
+          drifted << "#{basename}: toml=#{installed_value.inspect}, resolved default effort=#{expected_effort.inspect}"
+        end
+      else
+        unclassified << "#{basename}: toml=#{installed_value.inspect}, no resolved default (basename is in " \
+                         "neither AgentModels::TIER_DEFAULTS nor AgentModels::CONSULTATION_AGENTS in " \
+                         "scripts/lib/agent_models.rb; add it there, or set agents.models.codex.#{basename} " \
+                         "to sanction a model explicitly)"
+      end
+    end
+
+    if drifted.empty? && unclassified.empty?
+      message = if sanctioned.empty?
+                  "No agent-model drift (#{installed.size} installed Codex agent TOML(s) match the resolved default)"
+                else
+                  "No unsanctioned Codex agent-model drift; #{sanctioned.size} sanctioned override(s) in effect"
+                end
+      [check(
+        category: "core_files", name: "agent_model_drift", status: "pass",
+        message: message,
+        details: sanctioned
+      )]
+    else
+      parts = []
+      parts << "#{drifted.size} installed Codex agent TOML(s) have unsanctioned model drift vs the config-resolved default" if drifted.any?
+      parts << "#{unclassified.size} installed Codex agent TOML(s) have no resolved default in scripts/lib/agent_models.rb" if unclassified.any?
+      [check(
+        category: "core_files", name: "agent_model_drift", status: "warn",
+        message: parts.join("; "),
+        details: drifted + unclassified + sanctioned,
+        fixable: false
+      )]
+    end
+  end
+
   # --- Check category: manifest sync (binary core integrity) ---
 
   # Verify, for BOTH the global manifest and the agent-side manifest, that every

package/scripts/end-intent

@@ -67,6 +67,7 @@
 require "fileutils"
 require "date"
 require "open3"
+require "pathname"
 require_relative "lib/bridge"
 require_relative "lib/lock"
 require_relative "lib/intent_validator"
@@ -324,14 +325,25 @@ def git_toplevel(dir)
 end
 
 # Best-effort store commit: never raises, never blocks the mechanical close.
-# Returns true when a commit was created, false otherwise (not a git repo,
-# nothing to commit, or the commit failed). Pins a local committer identity so
-# the commit succeeds even with no ambient git config (hermetic).
-def store_commit(store, id, disposition)
+# Returns true when a commit was created, false otherwise (not a git repo, nothing to
+# commit, or the commit failed). Pins a local committer identity so the commit succeeds
+# even with no ambient git config (hermetic).
+#
+# SCOPED, never `git add -A` (D17, intent 197): stages only the completing intent's own
+# directory plus the store's INDEX.md, by explicit relative path. An unrelated dirty file
+# elsewhere in the store (another session's uncommitted work, a maintenance session's
+# in-flight change) is left exactly as it was found, never swept into this commit. This is
+# the safety floor that makes a concurrent maintenance session's change-plus-receipt safe on
+# the shared store checkout before intent 178 (store worktrees) lands.
+def store_commit(store, id, disposition, intent_dir:, index_path:)
   root = git_toplevel(store)
   return false if root.nil?
 
-  Open3.capture3("git", "-C", root, "add", "-A")
+  paths = [intent_dir, index_path].select { |p| p && File.exist?(p) }
+                                   .map { |p| relative_to(root, p) }
+  return false if paths.empty?
+
+  Open3.capture3("git", "-C", root, "add", "--", *paths)
   _out, _err, status = Open3.capture3(
     "git", "-C", root,
     "-c", "user.name=Plastic", "-c", "user.email=plastic@localhost",
@@ -340,6 +352,18 @@ def store_commit(store, id, disposition)
   status.success?
 end
 
+# `path`, relative to `root` (both absolute). Assumes `path` is inside `root` (true for
+# both intent_dir and index_path here, since both are derived from `store`, itself always
+# inside the same git repo `git_toplevel` resolved `root` from). Uses File.realpath, not
+# File.expand_path: `root` came back from `git rev-parse --show-toplevel`, which resolves
+# symlinked ancestors (e.g. macOS's /var -> /private/var), so an unresolved `path` can start
+# with a different prefix than `root` and produce a bogus, escaping relative path. Both
+# `path` and `root` are known to exist by the time this is called (the caller filters on
+# File.exist? first), so realpath is safe here.
+def relative_to(root, path)
+  Pathname.new(File.realpath(path)).relative_path_from(Pathname.new(File.realpath(root))).to_s
+end
+
 # --- pre-flight lock guard (D3/D4, intent 188) ------------------------------
 
 # Session resolution order (D3): explicit --session, else CLAUDE_CODE_SESSION_ID,
@@ -617,8 +641,9 @@ def main(argv)
   # 3. Savepoint Done bookend (idempotent).
   Bridge.append_terminal_savepoint(intent_dir, disposition)
 
-  # 4. Store auto-commit, unless --no-commit.
-  store_commit(store, id, disposition) unless opts[:no_commit]
+  # 4. Store auto-commit, unless --no-commit. Scoped to this intent's own paths (D17):
+  # never git add -A.
+  store_commit(store, id, disposition, intent_dir: intent_dir, index_path: index_path) unless opts[:no_commit]
 
   # 5. Disarm (D2/D16): dirty-worktree guard, disarm seam, lock verification.
   result = run_disarm(intent_dir, id, session, discard_worktree_changes: opts[:discard_worktree_changes])

package/scripts/hook-lock-gate

@@ -2,7 +2,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 #
-# Usage: hook-lock-gate <file_path> [session_id]
+# Usage: hook-lock-gate <file_path> [session_id] [harness]
 # Fail-CLOSED PreToolUse gate (intent 96). Blocks a mutating write to an active
 # intent's lifecycle dir when THIS session holds no live lock. Project code is NOT
 # gated here (D2). Emits the PreToolUse JSON deny contract at exit 0; reserves
@@ -16,9 +16,14 @@ begin
   file_path = ARGV[0]
   exit 0 unless file_path && !file_path.empty?
   session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_CODE_SESSION_ID"]
+  # Usage: hook-lock-gate <file_path> [session_id] [harness]. Claude's own bash
+  # shim never passes a third arg, so harness falls through to Lock's default
+  # (claude, slash form); scripts/codex-hook is the only caller that passes
+  # "codex" here (intent 201 D2).
+  harness = (ARGV[2] unless ARGV[2].to_s.empty?) || "claude"
 
   bridge_data = Bridge.discover_bridge(session: session, cwd: Dir.pwd)   # nil = no bridge cache
-  reason = Bridge.lock_gate_decision(bridge_data, file_path, session: session)
+  reason = Bridge.lock_gate_decision(bridge_data, file_path, session: session, harness: harness)
   unless reason
     # Allow path: refresh the lease for the session that holds this target's
     # lock (owner or delegate). Best-effort, never blocks.
@@ -37,7 +42,7 @@ begin
       dir = Bridge.intent_dir_for(file_path)
       artifact = File.basename(file_path) if dir
       if dir && artifact
-        claim_reason = Claim.claim_gate_reason(dir, artifact, session: session)
+        claim_reason = Claim.claim_gate_reason(dir, artifact, session: session, harness: harness)
         if claim_reason
           print JSON.generate(
             "hookSpecificOutput" => {

package/scripts/install.rb

@@ -40,10 +40,26 @@ class Install < InstallerCore
     puts "\n\u{1f9e0} Plastic v#{version}\n\n"
 
     if installed? && !reinstall
-      warn "Plastic v#{installed_version} is already installed."
-      warn "  - To upgrade:        npx @zalom/plastic update"
-      warn "  - To re-sync files:  npx @zalom/plastic install --reinstall"
-      return 1
+      # `installed?` is a GLOBAL check (is Plastic core installed for ANY
+      # harness), so it cannot by itself decide whether to refuse: once any
+      # agent is present, a machine that has NEVER installed a second harness
+      # (e.g. Codex, with no ~/.agents, no ~/.codex/hooks.json) must still be
+      # able to add it. Refuse only when EVERY selected agent already has its
+      # own registration (intent 198, D7); otherwise proceed with just the
+      # unregistered ones, and report the already-registered ones without
+      # silently re-syncing them (that is what --reinstall is for).
+      new_agents = selected.reject { |key| agent_installed?(key) }
+      if new_agents.empty?
+        warn "Plastic v#{installed_version} is already installed."
+        warn "  - To upgrade:        npx @zalom/plastic update"
+        warn "  - To re-sync files:  npx @zalom/plastic install --reinstall"
+        return 1
+      end
+
+      already_registered = selected - new_agents
+      run(selected: new_agents, force: force, reinstall: reinstall, ledger_action: ledger_action, argv: argv,
+          already_registered: already_registered)
+      return 0
     end
 
     run(selected: selected, force: force, reinstall: reinstall, ledger_action: ledger_action, argv: argv)
@@ -51,7 +67,11 @@ class Install < InstallerCore
   end
 
   # Hermetic entrypoint (no prompting / no exit). Returns the per-agent results array.
-  def run(selected:, force: false, reinstall: false, ledger_action: nil, argv: ARGV, input: $stdin)
+  # `already_registered` names agents the gate above found already registered:
+  # they are reported, never re-installed, so the summary line and the Codex
+  # trust reminder only ever count agents that actually changed this run.
+  def run(selected:, force: false, reinstall: false, ledger_action: nil, argv: ARGV, input: $stdin,
+          already_registered: [])
     fresh = !installed?
     mode = fresh ? :install : :update # :update here means "re-sync, skip bootstrap"
 
@@ -60,6 +80,7 @@ class Install < InstallerCore
     apply_config_flags(argv)
 
     results = selected.map { |key| install_for_agent(key, force, argv: argv, input: input, reinstall: reinstall) }
+    results += already_registered.map { |key| already_registered_result(key) }
 
     action = ledger_action || (fresh ? "install" : "reinstall")
     ledger_append(version, action)
@@ -114,10 +135,17 @@ class Install < InstallerCore
     argv[i + 1]
   end
 
+  def already_registered_result(key)
+    config = agent_config(key)
+    { agent: config[:name], success: false, already_registered: true }
+  end
+
   def print_results(results, mode)
     puts "\n\u{2014} Results \u{2014}\n\n"
     results.each do |r|
-      if r[:success]
+      if r[:already_registered]
+        puts "  \u{2139}  #{r[:agent]}: already registered, not re-synced (use --reinstall to re-sync)"
+      elsif r[:success]
         puts "  \u{2705} #{r[:agent]}: #{r[:files]} files installed"
       else
         puts "  \u{26a0}\u{fe0f}  #{r[:agent]}: #{r[:reason]}"
@@ -132,6 +160,23 @@ class Install < InstallerCore
     puts "   Registered for: #{installed.map { |r| r[:agent] }.join(", ")}"
     puts "   Run /clear (or restart your agent) to pick up new conventions."
     puts "   Next: read docs/guides/your-first-intent-in-10-minutes.md\n\n"
+
+    print_codex_hook_trust_reminder(installed)
+  end
+
+  # Codex hooks are installed but INERT until a human reviews and trusts each
+  # hook definition via /hooks (intent 198, Decision D2); Codex keys trust to
+  # the hook's current command hash, so a future release that changes a hook
+  # command re-arms the review. Printed only when a harness that declares its
+  # own home_dir (Codex today) actually installed successfully in this run.
+  # Data-driven from `agents`, never a hardcoded harness name, mirroring the
+  # same reasoning as the D1 presence-probe fix.
+  def print_codex_hook_trust_reminder(installed)
+    codex_like = agents.select { |a| a.key?(:home_dir) }
+    return if codex_like.none? { |a| installed.any? { |r| r[:agent] == a[:name] } }
+
+    puts "   Codex: open Codex, run /hooks, and trust the Plastic hook definitions."
+    puts "   Plastic's gates will not fire until you do.\n\n"
   end
 
   def show_help