@zalom/plastic 1.0.0-beta.23 → 1.0.0-beta.25

package/PLASTIC.md

@@ -283,32 +283,15 @@ hygiene after each intent. Advisory self-check, not hard-verifiable.
 
 ## Retrieval Gate
 
-A single capability-aware PreToolUse gate enforces retrieval-first routing on the agent's own
-Bash/Read/Grep/Glob calls (and on subagents, since PreToolUse binds them). The gate is
-OPERATION-based: it separates searching from reading, and it never stands between you and
-reading something you have already located.
-
-- Only CONTENT SEARCH over a Plastic store is gated. The Grep tool and bash `grep`/`rg`/`ag`
-  whose target is at or under a store route to QMD when QMD is present and the index is fresh:
-  the raw scan is blocked and you use `qmd search`/`qmd query` (or `scripts/qmd-sync search`)
-  instead. When QMD is present but stale, the search is allowed this turn and a background
-  reindex is fired so the next turn enforces against a fresh index; reindex is never
-  synchronous. When QMD is absent, the search is allowed.
-- Reading a known target (the Read tool, bash `cat`/`head`/`tail`) and structural discovery
-  (the Glob tool, bash `find`/`ls`) are always allowed, including over the store. QMD cannot
-  list directories or hand back one specific file, so these are never gated.
-- Code is never hard-gated here. Symbolic code navigation via Serena is a soft prompt mandate
-  (the UserPromptSubmit power-tools hook), not a block: content grep over code is allowed,
-  because Serena navigates symbols and cannot grep arbitrary strings.
-- QMD failure model. Absent or stale degrades to allow (stale also fires the background
-  reindex). A broken QMD, where the freshness probe errors or times out, also fails open, and
-  the hook emits a one-line warning so a degraded QMD is visible rather than silent.
-- Bypass: append a trailing `# qmd-ok` shell comment to a Bash command when you attempted
-  discovery and it did not serve you (no hits, or results that do not answer your need by your
-  reading of the snippets, not their score). A quoted or echoed occurrence does not bypass.
-  Bypasses are logged. The gate enforces that discovery was attempted, never that it succeeded.
-- Scope: only the agent's tool calls. Ruby `File.read` inside a script is invisible to the gate
-  and is out of scope by design.
+Advisory. Hard gates guard writes, locks, and structure, never reads or searches. Read,
+Grep, Glob, and bash search are always allowed, including over the stores. When QMD is
+present and fresh, a content search over store markdown receives an advisory hint pointing
+at `qmd search` alongside its result; when QMD is present but stale, a background reindex
+fires so the next turn's hint runs against a fresh index (never synchronous). QMD and
+Serena are recommendations, not obligations: the UserPromptSubmit power-tools hook appends
+one recommendation line per present tool. The legacy trailing `# qmd-ok` token is still
+accepted on Bash commands and simply silences the hint. Scope stays the agent's own tool
+calls; Ruby `File.read` inside a script is invisible to the hook by design.
 
 ## Context-economy measurement buckets (84a)
 
@@ -332,11 +315,28 @@ Hard blocking — hooks exit code 2 on gate failure.
 
 ## Delivery Isolation and the Single-Owner Lock
 
-Exactly one session or agent develops an intent's delivery at a time. Ownership is the armed
-session bridge, which doubles as the delivery lock: arming records the owning session, the
-owner pid, an acquired-at timestamp, and the host. Another session that finds an armed bridge
-for the same intent with a live owner backs off; if the owner pid is dead the lock is
-reclaimable. This is mandatory, not a convention.
+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
+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
+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
+mandatory, not a convention.
+
+Two locks share this schema (the two-lock doctrine): `delivery.lock` (exclusive, one owner
+plus delegates) and the future `maintenance.lock` (short TTL, structural move-and-record
+only). They are mutually exclusive in either direction; maintenance is allowed at any
+lifecycle stage provided no delivery lock is held. Intent 108 ships the delivery lock and
+the mutual-exclusion seam; the maintenance lock implementation follows intent 93 in a
+chained intent.
 
 Every code-touching intent gets its own git worktree named `{id}--{slug}`, and all code edits
 for that intent happen only inside it. Plastic provisions the worktree deterministically: it
@@ -350,6 +350,21 @@ Provisioning fails open for intents that touch no project code (pure research or
 intents in the global store, or a non-git repo): those get the lock only, and the worktree
 block stays unprovisioned. The fail-open path is always logged, never silent.
 
+### Intent delivery, station by station
+
+How one intent travels from boarding to Done, and what the lock, bridge, and gates do at
+each station.
+
+| Station | Delivered artifact | Lock and bridge steps | Pre-stage gate | Post-stage record |
+|---|---|---|---|---|
+| Start (board) | none (a procedure, not a stage) | `plastic-lock fix` self-heals stale, corrupt, or legacy state; arm acquires `delivery.lock` (O_EXCL, session-keyed), provisions the code worktree, writes the bridge cache | lock-gate denies any write into an active intent dir without this intent's lock; every deny names the resolving command | savepoint confirms the boarding station |
+| What (create) | `<id>--<slug>.md`, born complete | no lock yet; no bridge | create-gate validates the proposed intent content (Write, Edit, and MCP edits) | savepoint `What` line; intent listed in INDEX `## Active` |
+| Why | `spec.md` | owner writes refresh the lease (lock file mtime heartbeat) | gate-check requires the intent file with `## Intent` before spec.md; lock-gate admits only the owner or a delegate | savepoint `Why started`, `Why spec.md created` |
+| How | `plan.md`, `actions/`, `checklist.md` | heartbeat on writes; the code gate stays closed until plan.md plus checklist.md exist | gate-check requires spec.md before plan.md, and plan.md plus actions/ before checklist.md | savepoint `How started`, `How plan.md created`, `How checklist.md created`, `Exec started` |
+| Exec | code on the intent branch, checklist checked off | heartbeat; code edits confined to the provisioned worktree; delegates write under the owner's lock; bash, interpreter, and MCP writes gated the same way | code-gate, worktree-gate, bash-gate, lock-gate | checklist boxes; savepoint milestones |
+| End (done) | `outcome.md`, INDEX moves to Completed | ordered End tail: verify, merge and remove worktrees, disarm clears `delivery.lock`, only then is the bridge purge-eligible | gate-check blocks outcome.md while checklist items are unchecked | savepoint `Done delivered` (or `abandoned`); takeover audits, if any, remain in savepoint.md |
+| Maintenance (any stage) | `revisions.md` move-and-record entries | future `maintenance.lock` (short TTL), mutually exclusive with `delivery.lock` in either direction; 108 ships the schema seam only, the implementation follows intent 93 in a chained intent | acquisition refuses while the other lock type is fresh; a terminal intent with no lock held is read-only | dated, rule-tagged `revisions.md` entry; savepoint untouched |
+
 ## Deprecation Process
 
 Deprecations live in `deprecations.yml` and are shown at SessionStart. While Plastic is

package/hooks/code-gate

@@ -1,6 +1,15 @@
 #!/bin/bash
 INPUT=$(cat)
-FILE_PATH=$(echo "$INPUT" | ruby -rjson -e 'data = JSON.parse(STDIN.read); puts data.dig("tool_params", "file_path") || data.dig("tool_input", "file_path") || ""' 2>/dev/null)
+FILE_PATH=$(echo "$INPUT" | ruby -rjson -e '
+  data = JSON.parse(STDIN.read)
+  ti = data["tool_input"] || data["tool_params"] || {}
+  path = ti["file_path"] || ti["notebook_path"] || ti["relative_path"] || ""
+  if !path.empty? && !path.start_with?("/")
+    root = ti["project_root"] || data["cwd"] || ""
+    path = File.join(root, path) unless root.empty?
+  end
+  puts path
+' 2>/dev/null)
 
 if [ -z "$FILE_PATH" ]; then
   exit 0

package/hooks/hooks.json

@@ -19,7 +19,7 @@
     ],
     "PreCompact": [
       {
-        "matcher": "manual|auto",
+        "matcher": "",
         "hooks": [
           {
             "type": "command",
@@ -31,7 +31,7 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Write|Edit|NotebookEdit",
+        "matcher": "Write|Edit|NotebookEdit|mcp__serena__replace_content|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol|mcp__serena__safe_delete_symbol|mcp__serena__rename_symbol",
         "hooks": [
           {
             "type": "command",
@@ -56,7 +56,7 @@
         ]
       },
       {
-        "matcher": "Write",
+        "matcher": "Write|Edit|mcp__serena__replace_content|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol|mcp__serena__safe_delete_symbol|mcp__serena__rename_symbol",
         "hooks": [
           {
             "type": "command",

package/hooks/lock-gate

@@ -1,6 +1,15 @@
 #!/bin/bash
 INPUT=$(cat)
-FILE_PATH=$(echo "$INPUT" | ruby -rjson -e 'data = JSON.parse(STDIN.read); puts data.dig("tool_params", "file_path") || data.dig("tool_input", "file_path") || ""' 2>/dev/null)
+FILE_PATH=$(echo "$INPUT" | ruby -rjson -e '
+  data = JSON.parse(STDIN.read)
+  ti = data["tool_input"] || data["tool_params"] || {}
+  path = ti["file_path"] || ti["notebook_path"] || ti["relative_path"] || ""
+  if !path.empty? && !path.start_with?("/")
+    root = ti["project_root"] || data["cwd"] || ""
+    path = File.join(root, path) unless root.empty?
+  end
+  puts path
+' 2>/dev/null)
 
 if [ -z "$FILE_PATH" ]; then
   exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.0.0-beta.23",
+  "version": "1.0.0-beta.25",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/doctor.rb

@@ -20,6 +20,7 @@ require_relative "lib/intent_validator"
 require_relative "lib/graph_rebuild"
 require_relative "lib/links_projection"
 require_relative "lib/links_section"
+require_relative "lib/hook_registry"
 
 # Diagnostic engine, instantiable with an injected store/agent map so tests can
 # run it hermetically (no eval, no global-constant rewriting).
@@ -472,7 +473,10 @@ class Doctor
         category: "conventions", name: "section_structure", status: "warn",
         message: "#{bad_sections.size} intent file(s) have non-sanctioned ## sections",
         details: bad_sections.map { |b| "#{b[:dir]}: #{b[:issues].join(", ")}" },
-        fixable: false
+        fixable: true,
+        fix_hint: "Dispatch plastic-intent-curator to relocate each unsanctioned section into the " \
+                  "intent's revisions.md via move-and-record (a missing required section is restored " \
+                  "or reprojected instead); see PLASTIC.md > Structural maintenance and revisions.md"
       )
     end
 
@@ -698,7 +702,9 @@ class Doctor
     checks << graph_finding_check(
       "graph_i4_danglers", i4,
       "Every sources/chain id resolves to a real intent (I4)",
-      "Fix or remove the dangling id reference"
+      "Dispatch plastic-intent-curator to record the dangling sources/chain edge as a " \
+      "broken-source/broken-chain move-and-record entry in the intent's revisions.md (see " \
+      "PLASTIC.md > Structural maintenance and revisions.md), or restore the missing intent"
     )
     checks
   end
@@ -822,6 +828,45 @@ class Doctor
           fixable: true, fix_hint: "Re-run the Plastic installer: npx @zalom/plastic@latest --claude"
         )
       end
+
+      # hooks_match_registry (intent 108, D7): the live settings must carry
+      # EXACTLY the registrations HookRegistry defines; any drift (a missing
+      # gate, a stray plastic hook, a stale matcher) is how bash-gate shipped
+      # dead once already.
+      expected = HookRegistry.claude_settings_hooks(hook_dir: hooks_dir)
+      diffs = []
+      expected.each do |event, group|
+        groups = group.is_a?(Array) ? group : [group]
+        live = settings.dig("hooks", event) || []
+        groups.each do |g|
+          match = live.find { |h| h.is_a?(Hash) && h["matcher"] == g["matcher"] }
+          wanted = g["hooks"].map { |h| h["command"] }
+          got = match ? Array(match["hooks"]).map { |h| h["command"] } : []
+          missing = wanted - got
+          diffs << "#{event}[#{g['matcher']}] missing: #{missing.join(', ')}" unless missing.empty?
+        end
+      end
+      live_plastic = (settings["hooks"] || {}).flat_map do |event, groups|
+        Array(groups).flat_map do |g|
+          next [] unless g.is_a?(Hash) && g["hooks"].is_a?(Array)
+          g["hooks"].map { |h| h["command"].to_s }.select { |c| c.include?("plastic-") }
+                    .map { |c| "#{event}: #{c}" }
+        end
+      end
+      expected_cmds = expected.values.flat_map { |g| g.is_a?(Array) ? g : [g] }
+                              .flat_map { |g| g["hooks"].map { |h| h["command"] } }
+      strays = live_plastic.reject { |lp| expected_cmds.any? { |c| lp.end_with?(c) } }
+      diffs.concat(strays.map { |s| "stray: #{s}" })
+
+      checks << if diffs.empty?
+        check(category: "agent_registration", name: "hooks_match_registry",
+              status: "pass", message: "settings.json hooks match HookRegistry")
+      else
+        check(category: "agent_registration", name: "hooks_match_registry",
+              status: "fail", message: "#{diffs.size} hook registration(s) diverge from HookRegistry",
+              details: diffs, fixable: true,
+              fix_hint: "Re-run the installer merge: npx @zalom/plastic update (or ruby ~/.plastic/scripts/install.rb)")
+      end
     end
 
     # skills_exist — flat, hyphen-namespaced personal skills (plastic-<name>/)

package/scripts/hook-bash-gate

@@ -28,13 +28,31 @@ exit 0 if command.nil? || command.to_s.strip.empty?
 cwd = payload["cwd"]
 cwd = Dir.pwd if cwd.nil? || cwd.to_s.empty?
 
-# --- Load bridge (shared resolution; stdin session_id -> CLAUDE_CODE_SESSION_ID -> /tmp scan) ---
 session = payload["session_id"]
 session = ENV["CLAUDE_CODE_SESSION_ID"] if session.nil? || session.to_s.empty?
+
+# Auditable escape (intent 108, D7): a trailing `# plastic-ok` allows the
+# command and logs it, so sanctioned writes are visible, not silent.
+if Bridge.bash_escape?(command)
+  begin
+    require "fileutils"
+    log = File.join(Dir.home, ".plastic", ".cache", "gate-escapes.log")
+    FileUtils.mkdir_p(File.dirname(log))
+    File.open(log, "a") do |io|
+      io.puts("#{Time.now.utc.iso8601}\t#{session}\t#{command.gsub(/\s+/, ' ').strip}")
+    end
+  rescue StandardError
+    # the escape still applies; logging is best-effort
+  end
+  exit 0
+end
+
+# --- Load bridge (shared resolution; stdin session_id -> CLAUDE_CODE_SESSION_ID -> /tmp scan) ---
+# A nil bridge does NOT short-circuit (intent 108): the lock gate decides from
+# the durable delivery.lock file, so it must run even without a bridge cache.
 bridge_data = Bridge.discover_bridge(session: session, cwd: cwd)
-exit 0 unless bridge_data
 
-reason = Bridge.bash_gate_decision(bridge_data, command, cwd: cwd)
+reason = Bridge.bash_gate_decision(bridge_data, command, cwd: cwd, session: session)
 exit 0 unless reason
 
 $stderr.puts "PLASTIC GATE — #{reason}"

package/scripts/hook-create-gate

@@ -19,8 +19,13 @@
 # Reads the Claude Code PreToolUse payload as JSON on STDIN:
 #   { "tool_input": { "file_path": "...", "content": "..." } }
 # Empty / unparseable / non-matching path => exit 0 (cannot judge, allow).
-# Matching path but missing content => exit 2 (fail-safe: refuse to allow an
-# unvalidated intent write).
+# Three payload shapes on a matching path (intent 108, D7):
+#   Write (content):        validate the proposed content.
+#   Edit (old_string):      simulate the replacement on the on-disk file and
+#                           validate the RESULT; a missing file blocks.
+#   Pathless MCP mutation:  validate the CURRENT on-disk file (the PostToolUse
+#                           gate-check backstop validates the result); a
+#                           missing file blocks (fail-safe).
 
 require "json"
 require_relative "lib/intent_validator"
@@ -43,14 +48,45 @@ is_intent_file = dir.match?(%r{/store/[^/]+--[^/]+\z}) &&
                  File.basename(abs) == "#{File.basename(dir)}.md"
 exit 0 unless is_intent_file
 
-content = payload.dig("tool_input", "content") || payload.dig("tool_params", "content")
-if content.nil?
-  $stderr.puts "PLASTIC CREATE GATE — #{File.basename(abs)}: cannot read proposed content; " \
-               "refusing to allow an unvalidated intent write."
+input = payload["tool_input"] || payload["tool_params"] || {}
+content = input["content"]
+old_string = input["old_string"]
+
+def block!(lines)
+  Array(lines).each { |l| $stderr.puts l }
   exit 2
 end
 
-result = IntentValidator.validate_content(content)
+result =
+  if !content.nil?
+    # Write: validate the proposed content (intent 60b, unchanged).
+    IntentValidator.validate_content(content)
+  elsif !old_string.nil?
+    # Edit (intent 108, D7): simulate the replacement on the on-disk file and
+    # validate the RESULT, so an Edit can no longer sneak an intent file past
+    # the validator.
+    unless File.exist?(abs)
+      block!("PLASTIC CREATE GATE — #{File.basename(abs)} does not exist; " \
+             "create intents via new-intent / plastic-creating-intent.")
+    end
+    current = File.read(abs)
+    unless current.include?(old_string)
+      exit 0 # the Edit tool itself will fail; nothing lands, nothing to judge
+    end
+    simulated = input["replace_all"] ? current.gsub(old_string, input["new_string"].to_s)
+                                     : current.sub(old_string, input["new_string"].to_s)
+    IntentValidator.validate_content(simulated)
+  else
+    # Pathless mutation (MCP symbolic edits): the proposal is not visible at
+    # PreToolUse. Judge the CURRENT file: valid -> allow (the PostToolUse
+    # gate-check backstop validates the result), invalid/missing -> block.
+    unless File.exist?(abs)
+      block!("PLASTIC CREATE GATE — #{File.basename(abs)}: cannot read proposed " \
+             "content and no file exists; refusing to allow an unvalidated intent write.")
+    end
+    IntentValidator.validate_content(File.read(abs))
+  end
+
 exit 0 if result[:ok]
 
 $stderr.puts "PLASTIC CREATE GATE — #{File.basename(abs)} is not a valid intent:"

package/scripts/hook-gate-check

@@ -9,6 +9,7 @@
 require "json"
 require_relative "lib/bridge"
 require_relative "lib/intent_validator"
+require_relative "lib/lock"
 
 file_path = ARGV[0]
 exit 0 unless file_path && !file_path.empty?
@@ -72,6 +73,15 @@ intent_dir = "#{store}/#{dir}"
 # Normalize both paths for comparison
 bridge_intent_dir_abs = File.expand_path(intent_dir)
 
+# Lease heartbeat (intent 108, D1): every write by the session that owns (or
+# delegates under) the lock refreshes the delivery.lock mtime. Best-effort:
+# a heartbeat failure must never break the gate hook.
+begin
+  Lock.heartbeat(bridge_intent_dir_abs, session: session)
+rescue StandardError
+  # ignore
+end
+
 # Not inside intent dir = not our business
 exit 0 unless file_path_abs.start_with?("#{bridge_intent_dir_abs}/")
 

package/scripts/hook-lock-gate

@@ -10,15 +10,26 @@
 # reads never reach here.
 require "json"
 require_relative "lib/bridge"
+require_relative "lib/lock"
 
 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"]
 
-  bridge_data = Bridge.discover_bridge(session: session, cwd: Dir.pwd)   # nil = no lock held
-  reason = Bridge.lock_gate_decision(bridge_data, file_path)
-  exit 0 unless reason
+  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)
+  unless reason
+    # Allow path: refresh the lease for the session that holds this target's
+    # lock (owner or delegate). Best-effort, never blocks.
+    begin
+      dir = Bridge.intent_dir_for(file_path)
+      Lock.heartbeat(dir, session: session) if dir && !session.to_s.empty?
+    rescue StandardError
+      # ignore
+    end
+    exit 0
+  end
 
   print JSON.generate(
     "hookSpecificOutput" => {

package/scripts/hook-retrieval-gate

@@ -2,18 +2,20 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
-# PreToolUse retrieval gate (intent 84, Lever 2; operation-based redesign 89a).
-# Reads the tool call (JSON on stdin: tool_name + tool_input), computes
-# capabilities (QMD detect + freshness), delegates the decision to RetrievalGate,
-# and enforces:
-#   ALLOW = exit 0 ; BLOCK = exit 2 with reason on stderr (shown to the agent).
+# PreToolUse retrieval gate (intent 84, Lever 2; operation-based redesign 89a;
+# ADVISORY since intent 108, D8). Reads the tool call (JSON on stdin: tool_name +
+# tool_input), computes capabilities (QMD detect + freshness), and delegates the
+# decision to RetrievalGate. It NEVER blocks: reads and searches always run
+# (exit 0). A store content search that QMD could serve better gets a QMD hint
+# via PreToolUse additionalContext on stdout. Hard gates guard writes, locks,
+# and structure; never reads.
 # Fail-open: any parse error, timeout, or unexpected exception exits 0. On the
 # STALE QMD path RetrievalGate fires QmdSync.reindex_async (NEVER synchronous).
 # Binds subagents (PreToolUse hooks apply to subagent tool calls too).
 #
-# Only CONTENT SEARCH over store markdown is gated; reads and structural ops are
-# allowed. Code navigation is a soft prompt mandate (UserPromptSubmit power-tools),
-# not enforced here, so this hook no longer detects Serena.
+# Only CONTENT SEARCH over store markdown gets the hint; reads and structural
+# ops stay silent. Code navigation is a soft prompt recommendation
+# (UserPromptSubmit power-tools), not handled here.
 #
 # Scope: only the agent's own Bash/Read/Grep/Glob calls. Ruby `File.read` inside
 # scripts is invisible to a PreToolUse hook and is out of scope (no exemptions).
@@ -29,13 +31,13 @@ module RetrievalGateHook
   module_function
 
   # Pure-ish core: capabilities and reindex are injected so this is unit-testable
-  # with no real qmd. Returns [exit_code, stderr_string].
+  # with no real qmd. Returns [exit_code, stderr_string, stdout_json].
   #   stdin: raw PreToolUse JSON
   #   capabilities: { qmd:, qmd_fresh: }
   #   reindex: callable fired on the STALE path
   def run(stdin:, plastic_home:, cwd:, capabilities:, reindex: -> {})
     payload = parse(stdin)
-    return [0, nil] unless payload
+    return [0, nil, nil] unless payload
 
     tool_name = payload["tool_name"].to_s
     tool_input = payload["tool_input"]
@@ -49,14 +51,23 @@ module RetrievalGateHook
     ) { |_sig| bypassed = true }
 
     if reason
-      [2, "PLASTIC GATE — #{reason}"]
-    elsif bypassed
-      [0, "PLASTIC GATE — bypassed via # qmd-ok"]
+      # Advisory (intent 108, D8): reads and searches are never denied. The
+      # would-block reason becomes a hint the agent sees alongside the result.
+      hint = JSON.generate(
+        "hookSpecificOutput" => {
+          "hookEventName" => "PreToolUse",
+          "additionalContext" =>
+            "PLASTIC advisory: #{reason} (this search ran; the hint is not a block)"
+        }
+      )
+      [0, nil, hint]
     else
-      [0, nil]
+      # The `# qmd-ok` bypass token is still accepted (bypassed is set), but
+      # with nothing to bypass it no longer announces itself.
+      [0, nil, nil]
     end
   rescue StandardError
-    [0, nil] # fail-open
+    [0, nil, nil] # fail-open
   end
 
   def parse(raw)
@@ -120,7 +131,7 @@ if $PROGRAM_NAME == __FILE__
   plastic_home = (ARGV[0] && !ARGV[0].empty?) ? ARGV[0] : File.expand_path("~/.plastic")
   cwd = Dir.pwd
 
-  code, err = begin
+  code, err, out = begin
     caps = RetrievalGateHook.detect_capabilities(cwd: cwd)
     RetrievalGateHook.run(
       stdin: raw, plastic_home: plastic_home, cwd: cwd,
@@ -128,9 +139,10 @@ if $PROGRAM_NAME == __FILE__
       reindex: RetrievalGateHook.reindex_for(cwd: cwd, plastic_home: plastic_home)
     )
   rescue StandardError
-    [0, nil] # fail-open at the outermost boundary too
+    [0, nil, nil] # fail-open at the outermost boundary too
   end
 
   $stderr.puts(err) if err && !err.empty?
+  print out if out && !out.empty?
   exit code
 end