@vibelord/lanes 1.1.1 → 1.3.0

package/payload/lanes/container/lane-signal

@@ -1,7 +1,8 @@
 #!/usr/bin/env python3
-"""lane-signal <status> [--event NAME] [--harness claude|codex] [PAYLOAD] — the hook target of Claude Code and Codex
-inside a workspace container. Writes ~/.lz/state/hooks/<lane id>.json (atomic replace), which the host's
-lanes-statusd reads through /proc/<container init pid>/root and publishes as the lane's `agent{}` (source `hook`).
+"""lane-signal <status> [--event NAME] [--harness claude|codex] [--note TEXT] [--agent-pid PID] [PAYLOAD] — the hook
+target of Claude Code and Codex inside a workspace container, and the writer behind lane-mcp's `lanes_signal`. Writes
+~/.lz/state/hooks/<lane id>.json (atomic replace), which the host's lanes-statusd reads through /proc/<container init
+pid>/root and publishes as the lane's `agent{}` (source `hook`).
 
 The sidecar has its own directory because `lane-run`, the root process of every zmx-held lane, writes its
 `{phase, exit, at, pid}` record to ~/.lz/state/<zmx name>.json and exports LANE_ID=<zmx name> to the agent: a
@@ -10,7 +11,7 @@ this script writes state/hooks/, and lane-run never writes there.
 
     {"v":1, "lane":"<id>", "harness":"claude|codex", "status":"<agent{} vocabulary>", "since":<epoch the status
      began>, "at":<epoch of this event>, "event":"<hook event>", "pid":<agent pid>, "start":"<its starttime>",
-     "session":"<session/thread id or ''>"}
+     "session":"<session/thread id or ''>", "name":"<the agent's own note>" (only when there is one)}
 
 It never fails the agent and never speaks: every path exits 0 and nothing reaches stdout or stderr (a Claude Code
 UserPromptSubmit/SessionStart hook's stdout becomes model context). An unresolvable lane, a status outside the
@@ -20,15 +21,33 @@ Lane id: $LANE_ID — exported in a tmux lane only by a canonical/`--identity` r
 `lane open` never exports it), and in a zmx-held lane by `lane-run` as the zmx session name (which is NOT the
 `<ws>--z-<name>` id lanes-statusd publishes for it, so statusd does not join that sidecar to the zmx lane yet:
 DEF-1573) — else the pane's tmux session (`tmux -S ${TMUX%%,*} display -p -t $TMUX_PANE '#S'`) looked up by (socket
-name, session) in ~/.lz/registry.json, the projection `lanes sync` writes.
+name, session) in ~/.lz/registry.json, the projection `lanes sync` writes. lane-mcp passes the lane it resolved as
+$LANE_ID.
 
-Agent pid: the parent process, or that parent's parent when the parent is a shell (Claude Code runs a hook command
-through a shell, which may fork it rather than exec it; a pid that dies with the shell would read as a dead agent).
+Agent pid: --agent-pid when that process exists (lane-mcp passes its own parent, the agent that started it: the
+default rule below would name lane-mcp itself); else the parent process, or that parent's parent when the parent is
+a shell (Claude Code runs a hook command through a shell, which may fork it rather than exec it; a pid that dies
+with the shell would read as a dead agent).
 Session id: `session_id` of the hook's JSON on stdin, `thread-id` of a JSON PAYLOAD argument (Codex `notify` passes
-its JSON as the last argument), else $CLAUDE_SESSION_ID / $CODEX_THREAD_ID. Stdin is read only when it is not a
-terminal and for at most STDIN_WAIT seconds: a stdin that never closes cannot hang the hook.
-
-Same status as the file already holds (same session) keeps `since` and advances `at`; a new status starts `since`.
+its JSON as the last argument), else $CLAUDE_CODE_SESSION_ID / $CODEX_THREAD_ID (lane-mcp passes the first: Claude
+Code gives it to its MCP servers). Stdin is read only when it is not a terminal and for at most STDIN_WAIT seconds:
+a stdin that never closes cannot hang the hook.
+The same agent: the same process (pid and starttime: lane-mcp's parent and a hook's are the agent), else the same
+session when both writes name one (lane-mcp under Codex knows no session; the agent's hooks do).
+
+Same status as the file already holds (same session, or no session on one side and the same agent) keeps `since` and
+advances `at`; a new status starts `since`.
+Note (LNS-35): --note TEXT is the agent's own one-line account of what it is doing (`lanes_signal`), stored as the
+sidecar's `name` — the field the host already reads as an agent's task line (agent_state.read_sidecar_dict: the
+sidebar's task row, a notification's "lane: task — status") — with control characters dropped and cut to NOTE_MAX
+characters; `--note ''` clears it. Without --note the note is kept while the status repeats (a hook's PostToolUse
+`working` keeps a `working` note) and dropped when the status changes.
+The agent's own word (EXPLICIT, DEF-1801): a report with --event lanes_signal stands against the same agent's hooks
+that only say what the report already says better — the PostToolUse of the lanes_signal tool call itself (the hook
+fires for MCP tools too, on the very call that wrote the report), and, unless the report is `working`, the end of a
+turn (RESTING: Stop's needs_input/done, the idle Notification's needs_input). Those advance `at` and change nothing
+else. Any other event — the next tool call, a new prompt, a permission prompt, a failed turn, the session's end or
+start — is the agent doing something new and replaces the report as before.
 """
 import json
 import os
@@ -37,16 +56,22 @@ import select
 import subprocess
 import sys
 import time
+import unicodedata
 
 STATUSES = ('working', 'needs_input', 'needs_approval', 'done', 'errored', 'shell', 'idle')   # agent_state.STATUSES
 LANE_ID = re.compile(r'[A-Za-z0-9][A-Za-z0-9_.-]{0,127}')
 SHELLS = {'sh', 'dash', 'bash', 'zsh', 'ksh', 'fish'}
 STDIN_WAIT = 0.5
 STDIN_MAX = 1 << 20
+NOTE_MAX = 120
+EXPLICIT = 'lanes_signal'   # the --event of lane-mcp's lanes_signal: the agent's own word
+REPORT_TOOL = 'lanes_signal'   # its tool name; Claude Code names an MCP tool mcp__<server>__<tool>
+RESTING = {('Stop', 'needs_input'), ('Stop', 'done'), ('Notification', 'needs_input')}   # the hooks' "turn ended"
+SESSION_VARS = ('CLAUDE_CODE_SESSION_ID', 'CODEX_THREAD_ID')
 
 
 def options(argv):
-    status, event, harness, payload = (argv[0] if argv else ''), '', '', ''
+    status, event, harness, payload, note, agent_pid = (argv[0] if argv else ''), '', '', '', None, None
     rest = argv[1:]
     while rest:
         word = rest.pop(0)
@@ -54,9 +79,20 @@ def options(argv):
             event = rest.pop(0)
         elif word == '--harness' and rest:
             harness = rest.pop(0)
+        elif word == '--note' and rest:
+            note = clean_note(rest.pop(0))
+        elif word == '--agent-pid' and rest:
+            agent_pid = rest.pop(0)
         elif word.startswith('{'):
             payload = word
-    return status, event[:64], harness[:16], payload
+    return status, event[:64], harness[:16], payload, note, agent_pid
+
+
+def clean_note(text):
+    """One line of at most NOTE_MAX characters: control characters (C0, DEL, C1) and lone surrogates dropped,
+    whitespace runs collapsed — the host shows it in a terminal row and a notification."""
+    kept = ''.join(ch for ch in text if unicodedata.category(ch) not in ('Cc', 'Cs'))
+    return ' '.join(kept.split())[:NOTE_MAX]
 
 
 def lane_id(root):
@@ -87,7 +123,18 @@ def stat_fields(pid):
     return comm, text.rsplit(')', 1)[1].split()
 
 
-def agent():
+def agent(given=None):
+    """(pid, starttime) of the agent: `given` (--agent-pid) when that process exists, else the parent — or the
+    parent's parent when the parent is a shell."""
+    try:
+        pid = int(given) if given is not None else 0
+    except ValueError:
+        pid = 0
+    if pid > 1:
+        try:
+            return pid, stat_fields(pid)[1][19]
+        except (OSError, ValueError, IndexError):
+            pass   # gone (or never there): the parent rule below names the agent
     pid = os.getppid()
     try:
         comm, fields = stat_fields(pid)
@@ -99,12 +146,14 @@ def agent():
         return pid, None
 
 
-def stdin_session():
+def stdin_doc():
+    """The hook's JSON on stdin as a dict ({} when there is none): Claude Code and Codex pass `session_id`,
+    `hook_event_name` and, for a tool event, `tool_name`."""
     try:
         if os.isatty(0):
-            return ''
+            return {}
     except OSError:
-        return ''
+        return {}
     data, deadline = b'', time.monotonic() + STDIN_WAIT
     try:
         while len(data) < STDIN_MAX:
@@ -117,29 +166,46 @@ def stdin_session():
             data += chunk
         doc = json.loads(data.decode('utf-8', 'replace')) if data.strip() else {}
     except (OSError, ValueError):
-        return ''
-    return str(doc.get('session_id') or '') if isinstance(doc, dict) else ''
+        return {}
+    return doc if isinstance(doc, dict) else {}
+
+
+def report_call(tool):
+    """True for the lanes_signal tool itself, however the harness prefixes an MCP tool (mcp__lanes__lanes_signal)."""
+    return isinstance(tool, str) and re.split(r'__|[/.:]', tool)[-1] == REPORT_TOOL
+
+
+def same_agent(old, session, pid, start):
+    """`old` was written by this agent: the same process (pid and starttime; a session the agent cleared or resumed
+    is still its own, and lane-mcp's CLAUDE_CODE_SESSION_ID is the one it was started with), else the same session
+    when both name one (a hook run through two shells names a shell, not the agent)."""
+    if pid > 1 and old.get('pid') == pid and start is not None and old.get('start') == start:
+        return True
+    stored = str(old.get('session') or '')
+    return bool(session and stored and session == stored)
 
 
 def main(argv):
-    status, event, harness, payload = options(argv)
+    status, event, harness, payload, note, agent_pid = options(argv)
     if status not in STATUSES:
         return
     root = os.environ.get('LANE_ROOT') or os.path.join(os.path.expanduser('~'), '.lz')
     lane = lane_id(root)
     if not lane:
         return
-    session = stdin_session()
+    hook = stdin_doc()
+    session = str(hook.get('session_id') or '')
     if not session and payload:
         try:
             doc = json.loads(payload)
             session = str(doc.get('thread-id') or doc.get('session_id') or '') if isinstance(doc, dict) else ''
         except ValueError:
             session = ''
-    session = session or os.environ.get('CLAUDE_SESSION_ID') or os.environ.get('CODEX_THREAD_ID') or ''
+    session = (session or next((os.environ[key] for key in SESSION_VARS if os.environ.get(key)), ''))[:128]
+    given_harness = harness
     harness = harness or os.environ.get('LANE_HARNESS') or ('claude' if os.environ.get('CLAUDE_CODE_ENTRYPOINT')
                                                             else 'codex')
-    pid, start = agent()
+    pid, start = agent(agent_pid)
     now = int(time.time())
     state = os.path.join(root, 'state', 'hooks')   # never state/<id>.json: lane-run's phase record (DEF-1572)
     path = os.path.join(state, f'{lane}.json')
@@ -147,12 +213,26 @@ def main(argv):
         old = json.load(open(path))
     except (OSError, ValueError):
         old = None
-    session, since = session[:128], now
-    if (isinstance(old, dict) and old.get('v') == 1 and old.get('status') == status
-            and (not session or old.get('session') == session) and isinstance(old.get('since'), int)):
-        since, session = old['since'], session or str(old.get('session') or '')
-    doc = {'v': 1, 'lane': lane, 'harness': harness, 'status': status, 'since': since, 'at': now, 'event': event,
-           'pid': pid, 'start': start, 'session': session}
+    if not (isinstance(old, dict) and old.get('v') == 1 and old.get('status') in STATUSES
+            and isinstance(old.get('since'), int)):
+        old = None
+    stored = str((old or {}).get('session') or '')
+    if (old and old.get('event') == EXPLICIT and event != EXPLICIT and same_agent(old, session, pid, start)
+            and ((event == 'PostToolUse' and report_call(hook.get('tool_name')))
+                 or ((event, status) in RESTING and old['status'] != 'working'))):
+        # The agent's own report stands (EXPLICIT): this hook only says what the report already says better.
+        doc = dict(old, at=now, session=stored or session, harness=given_harness or old.get('harness') or harness)
+    else:
+        since = now
+        if (old and old['status'] == status
+                and (not session or stored == session or (not stored and same_agent(old, session, pid, start)))):
+            since, session = old['since'], session or stored
+            if note is None and isinstance(old.get('name'), str):
+                note = clean_note(old['name'])   # the same stretch keeps the agent's note; a new status drops it
+        doc = {'v': 1, 'lane': lane, 'harness': harness, 'status': status, 'since': since, 'at': now, 'event': event,
+               'pid': pid, 'start': start, 'session': session}
+        if note:
+            doc['name'] = note
     os.makedirs(state, exist_ok=True)
     tmp = os.path.join(state, f'.{lane}.json.{os.getpid()}.tmp')
     try: