plugin: show the user, after each turn, where an AxiomCode answer verifiably helped the agent (#1935)

plugins/axiomcode/hooks/assist.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Stop: when the turn's work stood on an AxiomCode answer, say so under the reply (#1935).
+
+Agents finish with and without the graph, and they rarely credit the answer they acted on, so the user never sees what
+it did. At the end of each turn this reads the session's transcript and prints, for each chain new in that turn, one
+line the user can check (skills/axiomcode/scripts/ax_assists.py holds the rules):
+
+    ◆ AxiomCode this turn · 1 answer led the agent's work
+      • Helped: `impact total` showed pricing.py (new to the agent) → it edited it → both picked test files (…) pass
+
+Rules it holds itself to:
+  · NOTHING FROM THE AGENT'S TEXT. The reply has already been shown when this runs; every link is read from the tool
+    calls and their results, and a link that was not checked is not printed.
+  · SILENT unless an answer led somewhere: no query, or a query nobody acted on, prints nothing. Only what helped is
+    counted; the answers that led nowhere are never shown.
+  · THE AGENT QUOTES IT. In Claude Code the receipt goes back to the agent once (decision "block"), which ends its
+    reply with it word for word, so it is part of the answer in every client (`-p`, the SDK, an IDE). The second stop
+    (stop_hook_active) checks the reply carries every line; when it does not, the receipt is shown as a message
+    instead. Cursor and Gemini cannot hand it back, so they get the message.
+AXIOMCODE_ASSISTS=off turns it off.
+"""
+import json, os, subprocess, sys, time
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), 'skills', 'axiomcode', 'scripts'))
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import _host
+
+if (os.environ.get('AXIOMCODE_ASSISTS') or '').lower() in ('off', '0', 'false', 'no'):
+    sys.exit(0)
+try:
+    ev = _host.read()
+except Exception:
+    sys.exit(0)
+if _host.CURSOR:                              # Cursor's stop hook takes no message for the user
+    sys.exit(0)
+tr = ev.get('transcript_path') or ''
+if not tr or not os.path.isfile(tr):
+    sys.exit(0)
+cwd = ev.get('cwd') or os.getcwd()
+try:
+    r = subprocess.run(['git', '-C', cwd, 'rev-parse', '--show-toplevel'], capture_output=True, text=True, timeout=5)
+    root = r.stdout.strip() if r.returncode == 0 and r.stdout.strip() else cwd
+except Exception:
+    root = cwd
+ASK = ('AxiomCode checked the tool calls of this turn and recorded where its answers led your work. End your reply with '
+       'the block below, copied exactly as written (inside a ``` block), and nothing else: run no tools, add no claims '
+       'of your own about it.\n\n')
+
+
+def _pending(root):
+    return os.path.join(root, '.axiomcode', 'assists.pending.json')
+
+
+def _quoted(transcript, msg):
+    """whether the agent's text after the hand-back carries every line of the receipt"""
+    want = [l.strip() for l in msg.splitlines() if l.strip()]
+    for _ in range(6):                        # the host may still be writing the reply's last message
+        said, after = [], False
+        for line in open(transcript, encoding='utf-8', errors='replace'):
+            try:
+                e = json.loads(line)
+            except ValueError:
+                continue
+            c = (e.get('message') or {}).get('content') if isinstance(e, dict) else None
+            if e.get('type') == 'user' and ASK[:40] in json.dumps(c, ensure_ascii=False):
+                said, after = [], True
+            elif after and e.get('type') == 'assistant' and isinstance(c, list):
+                said += [x.get('text') or '' for x in c if isinstance(x, dict) and x.get('type') == 'text']
+        text = '\n'.join(said)
+        if all(w in text for w in want):
+            return True
+        time.sleep(0.5)
+    return False
+
+
+if ev.get('stop_hook_active'):
+    # the agent was handed the receipt; show it as a message only when its reply did not carry it
+    try:
+        pend = json.load(open(_pending(root)))
+        os.remove(_pending(root))
+    except Exception:
+        sys.exit(0)
+    if pend.get('session') == str(ev.get('session_id') or '') and not _quoted(tr, pend['msg']):
+        print(json.dumps({'systemMessage': pend['msg']}))
+    sys.exit(0)
+try:
+    import ax_assists
+    msg = ax_assists.at_stop(tr, os.path.realpath(root), str(ev.get('session_id') or ''))
+except Exception:
+    sys.exit(0)                               # a receipt is never worth a failed turn
+if not msg:
+    sys.exit(0)
+if _host.GEMINI:
+    print(json.dumps({'systemMessage': msg}))
+    sys.exit(0)
+try:
+    json.dump({'session': str(ev.get('session_id') or ''), 'msg': msg}, open(_pending(root), 'w'))
+    print(json.dumps({'decision': 'block', 'reason': ASK + msg}))
+except Exception:
+    print(json.dumps({'systemMessage': msg}))

plugins/axiomcode/hooks/hooks.json

@@ -72,6 +72,15 @@
       "timeout": 5
      }
     ]
+   },
+   {
+    "hooks": [
+     {
+      "type": "command",
+      "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run.js\" assist.py",
+      "timeout": 15
+     }
+    ]
    }
   ],
   "SessionStart": [

plugins/axiomcode/skills/axiomcode/SKILL.md

@@ -123,6 +123,15 @@ With them, a call into a dependency resolves to its declaration and a chain is t
 types (`client.post(...).json()`). Library bodies are not walked, so a dependency calling back into the project is
 not found this way.
 
+## report
+
+At the end of a turn where an answer verifiably led your work (a file the answer showed first that you then read or
+edited, or the tests it picked that you ran: Redirected / Helped / Useful), the plugin hands you a receipt once. End
+your reply with it exactly as written. It is read from the session's tool calls, not from what you write, so there is
+nothing to claim yourself; if the reply does not carry it, the user is shown it anyway.
+Each repository keeps its own record (`.axiomcode/assists.jsonl` at its root) and its own page,
+`.axiomcode/assists.html`, rebuilt whenever a turn adds to the record; `axiomcode report` rebuilds it by hand.
+
 ## graph
 
 `axiomcode graph` draws the codebase as one page for the user to look at: directories, files, types and methods, with