@zalom/plastic 1.4.0 → 1.4.1

package/PLASTIC.md

@@ -99,6 +99,11 @@ tags: [plastic, architecture]
 | **How** | Planning | `plan.md` + `actions/ACTION_N.md` (at least one) + `checklist.md` | `plastic-intent-planning` |
 | **Exec** | Execution | `outcome.md` | `plastic-intent-executing` |
 
+Invoke a skill for your harness: Claude Code uses the slash form (`/plastic-intent-creating`);
+Codex CLI uses a dollar prefix instead (`$plastic-intent-creating`), and may also select a skill
+implicitly by matching its description. Skill names elsewhere in this document are given bare
+(`plastic-intent-creating`); add the prefix for your harness.
+
 `## Insights` is the append-only log of durable discoveries captured throughout ALL stages.
 An insight is a discovery worth keeping for later reads: novel, or old but newly relevant,
 surfaced at any stage (What, Why, How, Exec). It is the most interesting residue of an
@@ -288,8 +293,8 @@ Beyond the lifecycle agents, Plastic ships thin skills for day-to-day operation:
 - **`plastic-feedback`** (intent 174) turns a described Plastic quirk, bug, or feature idea
   into a redacted local report file and a prefilled GitHub issue URL; only the user can submit
   it. `disable-model-invocation` hides its description from your own context, so if the user
-  hits a Plastic quirk, bug, or missing feature, offer to run `/plastic-feedback` yourself
-  instead of waiting to be asked; the user still sends it, you never do.
+  hits a Plastic quirk, bug, or missing feature, offer to invoke the plastic-feedback skill
+  yourself instead of waiting to be asked; the user still sends it, you never do.
 
 ## Releases and Versioning
 
@@ -505,18 +510,31 @@ Each gate guards one thing. All are hard except the retrieval gate:
 
 Exactly one session or agent develops an intent's delivery at a time. Ownership is
 session-keyed and durable: arming acquires `delivery.lock` inside the intent directory
-(atomically, O_EXCL), recording the owner session, the host, the acquired-at time, a
-delegates list, and the lock type. Liveness is a lease: the owner's hooks refresh the lock
-file's mtime on tool activity, and the lock counts as stale only when that heartbeat is
-older than the TTL. No process id is consulted anywhere. The /tmp session bridge is a cache
+(atomically, O_EXCL). The session id is the authorization identity. Descriptive provenance
+records the controller's explicit `harness`, `agent`, `model`, `thread`, and `mode` values,
+but never grants access and is never inferred from transcripts or filesystem paths. Missing
+fields on legacy locks display as `Unknown`. Liveness is a lease: the owner's hooks refresh
+the lock file's mtime on tool activity, and that mtime is the sole heartbeat truth. The lock
+counts as stale only when the mtime is older than the TTL. No process id is consulted anywhere.
+The /tmp session bridge is a cache
 of this state; on any disagreement, or when the bridge is missing, the lock file wins.
 Another session that finds a fresh lock backs off; a stale lock is reclaimed only by
 explicit takeover, which replaces the lock and appends an audit line to the intent's
-savepoint.md. Subagents spawned by the owner write under the owner's lock once registered
-as delegates. Disarm clears the lock; the End tail is ordered: verify, merge and remove
+savepoint.md. Rearming the same session preserves its acquired identity and refreshes known
+provenance; an explicit takeover replaces the controller and starts new provenance.
+Subagents spawned by the owner write under the owner's lock once registered as delegates.
+Delegate activity status (`active`, `finished`, or `failed`) is descriptive and does not revoke
+the session's string-array authorization. A registered delegate remains authorized until a
+separate authorization-removal mechanism exists. Finished and failed delegate activity is
+retained as descriptive history, bounded to the 20 most recent terminal entries. A controller,
+a delegate, and an artifact claim are distinct evidence: controller ownership authorizes the
+delivery, delegate registration authorizes a child session, and a claim selects one current
+writer for one artifact. Disarm clears the lock; the End tail is ordered: verify, merge and remove
 worktrees, clear the lock, and only then is the bridge purge-eligible. Repair is one
-idempotent function with two entry points: the `plastic-lock` command (status, fix,
-release, reclaim, delegate) and `/plastic-intent-starting`, so boarding self-heals. This is
+idempotent function with two entry points: the `plastic-lock` command (`who`, status, fix,
+release, reclaim, delegate) and `/plastic-intent-starting`, so boarding self-heals. `who` is
+read-only and reports the controller, mtime heartbeat, delegates, and claims from durable files.
+This is
 mandatory, not a convention.
 
 Solo-mode gate defaults (intent 128): on a confirmed positive solo determination
@@ -658,4 +676,3 @@ the lock-bounded post-done window with its keep-guard test. Intent 111 owns the
 liveness surface, the lock-issue message, orchestrator auto-repair, and the fail-open
 behavior itself. Intent 112 owns the maintenance lock and the immutability gate (it inherits
 fail-open from 111). Intent 4a1b1 owns deep agent stuck-detection and is not superseded.
-

package/package.json

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

package/scripts/codex-hook

@@ -2,18 +2,57 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 #
-# Usage: codex-hook <gate>   (gate: code-gate | lock-gate | savepoint-pre | gate-check | create-gate)
+# Usage: codex-hook <gate>
+#   file-mutation gates: code-gate | lock-gate | savepoint-pre | gate-check | create-gate | links-gate
+#   live-state hooks (intent 199): session-start | check-update | continue |
+#     future-intent-check | auto-arm | qmd-search | savepoint
+#   shell-tool gates (intent 203): bash-gate | retrieval-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).
+# The Codex input adapter (intent 102, extended by 199 and 203). Reads a Codex
+# hook stdin payload once. Three shapes exist and the gate name alone selects
+# which path runs (Codex's own hooks.json registration guarantees they never
+# cross): the file-mutation gates read session_id at top level and the
+# apply_patch command in tool_input.command [guide Part 4], parse the diff
+# envelope via ApplyPatchEnvelope, and drive Plastic's payload-agnostic Ruby
+# gate/savepoint cores once per file operation, relaying stdout/stderr/exit
+# unchanged. The live-state hooks carry no tool_input at all (they are not tool
+# calls); the dispatcher execs the SAME launcher file Claude already runs for
+# that hook (hooks/<name>), which is already harness-agnostic (resolves
+# ~/.plastic off $HOME, reads only the common stdin fields the guide confirms
+# Codex shares with Claude for these three events), so the body is reused, not
+# rewritten (D3). The shell-tool gates (bash-gate, retrieval-gate) report
+# tool_name: "Bash" with the command in tool_input.command, but MUST NOT be
+# routed through ApplyPatchEnvelope.parse below: a plain shell command has no
+# *** Begin Patch/*** End Patch envelope, so it would parse to an empty op list
+# and hit this file's own `exit 0 if ops.empty?` line, silently allowing every
+# Bash call and reopening the exact hole intent 203 closes. So these two exec
+# the SAME scripts/hook-bash-gate / scripts/hook-retrieval-gate files Claude
+# already runs, unmodified, the identical "drive the body, relay its output"
+# pattern used for the live-state hooks. The one adaptation shared by both the
+# live-state and shell-tool paths is threading the payload's session_id into
+# CLAUDE_CODE_SESSION_ID, since Codex's own process env never carries it, plus
+# a bounded timeout: hooks/check-update backgrounds a real npm network call
+# without redirecting its output away from the inherited stdout/stderr pipes,
+# and Codex invokes hooks synchronously, so without a bound a slow network call
+# could hold this dispatcher's pipe open past the launcher's own (fast) exit.
 require "json"
+require "open3"
 require "rbconfig"
+require "timeout"
 require_relative "lib/apply_patch_envelope"
 require_relative "lib/intent_validator"
+require_relative "lib/links_gate"
+
+# Sync stdout so a relayed launcher's stdout and stderr land on the merged
+# pipe in call order. Ruby buffers STDOUT (but not STDERR) when it is not a
+# TTY; without this, `warn err` below can reach the OS pipe before a
+# preceding `print out` is flushed, corrupting the relayed JSON for any
+# caller that merges the dispatcher's own stdout and stderr.
+$stdout.sync = true
+
+STATE_HOOKS = %w[session-start check-update continue future-intent-check auto-arm qmd-search savepoint].freeze
+STATE_TIMEOUT = 5
+SHELL_HOOKS = %w[bash-gate retrieval-gate].freeze
 
 gate = ARGV[0].to_s
 raw = ($stdin.read rescue nil)
@@ -22,7 +61,49 @@ payload = (JSON.parse(raw) rescue nil)
 exit 0 unless payload.is_a?(Hash)
 
 session = payload["session_id"].to_s
+
+if STATE_HOOKS.include?(gate)
+  launcher = File.expand_path(File.join(__dir__, "..", "hooks", gate))
+  cwd = payload["cwd"].to_s
+  cwd = Dir.pwd if cwd.empty? || !Dir.exist?(cwd)
+  env = { "CLAUDE_CODE_SESSION_ID" => (session.empty? ? nil : session) }
+  out, err, status = begin
+    Timeout.timeout(STATE_TIMEOUT) { Open3.capture3(env, launcher, stdin_data: raw, chdir: cwd) }
+  rescue StandardError
+    ["", "", nil] # fail open: launcher missing, unexecutable, crashed, or too slow
+  end
+  print out unless out.to_s.empty?
+  warn err unless err.to_s.empty?
+  exit(status ? status.exitstatus : 0)
+end
+
+if SHELL_HOOKS.include?(gate)
+  # bash-gate / retrieval-gate (intent 203): a shell command has no apply_patch
+  # diff envelope, so this branch execs the SAME scripts/hook-bash-gate /
+  # scripts/hook-retrieval-gate files Claude already runs, unmodified, and
+  # relays their exit code and stderr. It must never fall through to
+  # ApplyPatchEnvelope.parse below (see header comment).
+  cwd = payload["cwd"].to_s
+  cwd = Dir.pwd if cwd.empty? || !Dir.exist?(cwd)
+  env = { "CLAUDE_CODE_SESSION_ID" => (session.empty? ? nil : session) }
+  script = File.join(__dir__, "hook-#{gate}")
+  argv = [script]
+  # hook-retrieval-gate reads plastic_home off ARGV[0] (mirrors hooks/retrieval-gate's
+  # own launcher, which passes "$HOME/.plastic"); hook-bash-gate takes no args, it
+  # resolves Dir.home directly.
+  argv << ENV.fetch("PLASTIC_HOME") { File.join(Dir.home, ".plastic") } if gate == "retrieval-gate"
+  out, err, status = begin
+    Timeout.timeout(STATE_TIMEOUT) { Open3.capture3(env, RbConfig.ruby, *argv, stdin_data: raw, chdir: cwd) }
+  rescue StandardError
+    ["", "", nil] # fail open: script missing, unexecutable, crashed, or too slow
+  end
+  print out unless out.to_s.empty?
+  warn err unless err.to_s.empty?
+  exit(status ? status.exitstatus : 0)
+end
+
 command = payload.dig("tool_input", "command") || payload.dig("tool_params", "command")
+exit 0 if command.nil? # fail-open: no tool_input at all (unrecognized gate name or non-tool-call payload)
 ops = ApplyPatchEnvelope.parse(command)
 exit 0 if ops.empty? # fail-open: nothing parseable to gate
 
@@ -55,8 +136,11 @@ when "create-gate"
 
 when "lock-gate"
   # Deny is signalled by JSON on stdout at exit 0. Relay the first deny.
+  # "codex" is threaded as the harness (intent 201 D2): hook-lock-gate renders
+  # any deny reason with the $plastic-<name> form instead of Claude's default
+  # slash.
   ops.each do |o|
-    out, _ = run_core("hook-lock-gate", o.path, session)
+    out, _ = run_core("hook-lock-gate", o.path, session, "codex")
     if out.include?('"permissionDecision":"deny"') || out.include?('"permissionDecision": "deny"')
       print out
       exit 0
@@ -91,6 +175,36 @@ when "savepoint-pre"
   ops.each { |o| run_core("hook-savepoint-pre", o.path) }
   exit 0
 
+when "links-gate"
+  # Write-time belt for the PLASTIC.md ## Links contract (intent 192), reusing
+  # the SAME LinksGate.decision Claude's hook-links-gate already drives, so
+  # both harnesses share one decision function. before_content is the real
+  # on-disk file (File.read, or "" when it does not yet exist); after_content
+  # is the proposed result, o.added_content.
+  #
+  # DISCLOSED, NARROWER judgment than Claude's version (intent 198, Decision
+  # D3): ApplyPatchEnvelope.parse only ever captures a diff's ADDED lines,
+  # never its removed or context lines, so for an Update whose diff is a
+  # partial hunk rather than a full-file rewrite, after_content may not be the
+  # complete proposed file. This is the same class of disclosed limitation
+  # create-gate already carries for Update/Delete/Move (best effort, never a
+  # hard crash). links-gate has no PostToolUse backstop to defer to on Claude
+  # either, so running this best-effort compare on Update ops too is strictly
+  # more coverage than the prior total fail-open.
+  ops.each do |o|
+    next unless intent_file?(o.path)
+
+    before_content = File.exist?(o.path) ? File.read(o.path) : ""
+    plastic_home = ENV.fetch("PLASTIC_HOME") { File.join(Dir.home, ".plastic") }
+    reason = LinksGate.decision(file_path: o.path, before_content: before_content,
+                                 after_content: o.added_content.to_s, plastic_home: plastic_home)
+    next unless reason
+
+    $stderr.puts reason
+    exit 2
+  end
+  exit 0
+
 else
   exit 0
 end