system-diff 0.4.2__tar.gz → 0.4.3__tar.gz

{system_diff-0.4.2 → system_diff-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: system-diff
-Version: 0.4.2
+Version: 0.4.3
 Summary: Draws your system from its code (parts, entry points, data, outside systems) and what each change adds, changes or removes. No dependencies; SVG pictures for PRs and READMEs.
 Project-URL: Homepage, https://github.com/simplifiedmachine/system-diff
 Project-URL: Documentation, https://github.com/simplifiedmachine/system-diff/wiki
@@ -132,8 +132,8 @@ Claude does most work alone unless asked otherwise, so system-diff asks it to pl
 - **The bus:** an async publish/subscribe channel whose topics are the blocks. Each agent follows the blocks its own
   depend on. Every change an agent makes to a block's structure is published on that block's topic as it happens
   ("API no longer answers DELETE /orders/{id}"), with why it matters. Agents publish their own notes with `publish`
-  (to a block, to "all", or to "agent:<name>"). Each agent's unread messages reach it with its next tool result:
-  nobody waits on anybody.
+  (to a block, to "all", or to "agent:<name>"). Each agent's unread messages reach it with its next tool result
+  of any kind (a read, an edit, a shell command, a search), once: nobody waits on anybody.
 - **Claims:** `claim` gives an agent its blocks. An edit to someone else's block is published to its owner and shown
   under Needs your attention.
 - **One agent, one area:** when an agent (the main conversation included) edits blocks in two or more areas in one
@@ -146,6 +146,8 @@ The MCP tools: `plan_agents`, `claim`, `publish`, `subscribe`, `inbox`, `team`.
 
 - **After an edit that changes the system's structure**, one line under it: "System diff: API now answers GET
   /health · a new way in: it needs the same checks as the others". Edits that change no structure stay quiet.
+- **Messages from other agents** on the bus arrive with an agent's next tool result of any kind, not only after
+  an edit.
 - **At the end of each turn**, one line on what the turn did to the system, or which parts it edited when the
   structure stayed the same; nothing for a turn that only talked.
 - **Ask Claude** "what is the API part?" or "what does this change do?": the MCP server gives it `explain` (the facts

{system_diff-0.4.2 → system_diff-0.4.3}/README.md

@@ -100,8 +100,8 @@ Claude does most work alone unless asked otherwise, so system-diff asks it to pl
 - **The bus:** an async publish/subscribe channel whose topics are the blocks. Each agent follows the blocks its own
   depend on. Every change an agent makes to a block's structure is published on that block's topic as it happens
   ("API no longer answers DELETE /orders/{id}"), with why it matters. Agents publish their own notes with `publish`
-  (to a block, to "all", or to "agent:<name>"). Each agent's unread messages reach it with its next tool result:
-  nobody waits on anybody.
+  (to a block, to "all", or to "agent:<name>"). Each agent's unread messages reach it with its next tool result
+  of any kind (a read, an edit, a shell command, a search), once: nobody waits on anybody.
 - **Claims:** `claim` gives an agent its blocks. An edit to someone else's block is published to its owner and shown
   under Needs your attention.
 - **One agent, one area:** when an agent (the main conversation included) edits blocks in two or more areas in one
@@ -114,6 +114,8 @@ The MCP tools: `plan_agents`, `claim`, `publish`, `subscribe`, `inbox`, `team`.
 
 - **After an edit that changes the system's structure**, one line under it: "System diff: API now answers GET
   /health · a new way in: it needs the same checks as the others". Edits that change no structure stay quiet.
+- **Messages from other agents** on the bus arrive with an agent's next tool result of any kind, not only after
+  an edit.
 - **At the end of each turn**, one line on what the turn did to the system, or which parts it edited when the
   structure stayed the same; nothing for a turn that only talked.
 - **Ask Claude** "what is the API part?" or "what does this change do?": the MCP server gives it `explain` (the facts

{system_diff-0.4.2 → system_diff-0.4.3}/docs/diagrams/system.json

@@ -9,7 +9,7 @@
    "container": "",
    "declared": true,
    "files": 3,
-   "lines": 313,
+   "lines": 314,
    "hub": false,
    "quiet": false
   },
@@ -33,7 +33,7 @@
    "container": "",
    "declared": true,
    "files": 1,
-   "lines": 456,
+   "lines": 462,
    "hub": false,
    "quiet": false
   },
@@ -45,7 +45,7 @@
    "container": "",
    "declared": true,
    "files": 1,
-   "lines": 296,
+   "lines": 368,
    "hub": false,
    "quiet": false
   },
@@ -69,7 +69,7 @@
    "container": "",
    "declared": true,
    "files": 1,
-   "lines": 521,
+   "lines": 531,
    "hub": false,
    "quiet": false
   },
@@ -201,7 +201,7 @@
    "container": "",
    "declared": true,
    "files": 2,
-   "lines": 732,
+   "lines": 745,
    "hub": false,
    "quiet": false
   },
@@ -317,8 +317,10 @@
   "agent>learn": 1,
   "agent>sources": 1,
   "agents>activity": 1,
-  "agents>architecture": 1,
+  "agents>architecture": 2,
+  "agents>config": 1,
   "agents>design": 1,
+  "agents>extract": 1,
   "agents>sources": 1,
   "architecture>design": 2,
   "architecture>diff": 1,
@@ -433,7 +435,8 @@
   ],
   "agent>agents": [
    "ORCHESTRATE",
-   "after_edit"
+   "after_edit",
+   "deliver"
   ],
   "agent>companion": [
    "add_vscode_task",
@@ -466,22 +469,28 @@
   ],
   "agents>activity": [
    "EDIT",
-   "_replace",
    "PROMPT",
-   "READ",
+   "_replace",
    "is_system",
-   "part_of"
+   "part_of",
+   "READ"
   ],
   "agents>architecture": [
    "groups_of"
   ],
+  "agents>config": [
+   "lenient"
+  ],
   "agents>design": [
    "depends",
+   "kinds",
    "and_list",
    "fan_in",
-   "kinds",
    "summarize"
   ],
+  "agents>extract": [
+   "Code"
+  ],
   "agents>sources": [
    "git_dir"
   ],

{system_diff-0.4.2 → system_diff-0.4.3}/docs/diagrams/system.svg

@@ -64,9 +64,11 @@ text { font-family: 'Segoe UI', FreeSans, 'Helvetica Neue', Arial, sans-serif; }
 <path class="be k-call s-same" d="M214,172 C243,172 243,188 272,188" marker-end="url(#ar-call-same)"><title>agent → extract</title></path>
 <path class="be k-call s-same" d="M214,172 C243,172 243,788 272,788" marker-end="url(#ar-call-same)"><title>agent → learn</title></path>
 <path class="be k-call s-same" d="M214,172 C246,172 246,99 278,99 L478,99 C507,99 507,52 536,52" marker-end="url(#ar-call-same)"><title>agent → sources</title></path>
-<path class="be k-call s-same" d="M478,488 C507,488 507,112 536,112" marker-end="url(#ar-call-same)"><title>agents → activity</title></path>
 <path class="be k-call s-same" d="M478,488 C514,488 514,428 484,428" marker-end="url(#ar-call-same)"><title>agents → architecture</title></path>
+<path class="be k-call s-same" d="M478,488 C507,488 507,112 536,112" marker-end="url(#ar-call-same)"><title>agents → activity</title></path>
+<path class="be k-call s-same" d="M478,488 C544,488 544,128 484,128" marker-end="url(#ar-call-same)"><title>agents → config</title></path>
 <path class="be k-call s-same" d="M478,488 C514,488 514,548 484,548" marker-end="url(#ar-call-same)"><title>agents → design</title></path>
+<path class="be k-call s-same" d="M478,488 C544,488 544,188 484,188" marker-end="url(#ar-call-same)"><title>agents → extract</title></path>
 <path class="be k-call s-same" d="M478,488 C507,488 507,52 536,52" marker-end="url(#ar-call-same)"><title>agents → sources</title></path>
 <path class="be k-call s-same" d="M478,428 C524,428 524,548 484,548" marker-end="url(#ar-call-same)"><title>architecture → design</title></path>
 <path class="be k-call s-same" d="M478,428 C524,428 524,308 484,308" marker-end="url(#ar-call-same)"><title>architecture → graph</title></path>

{system_diff-0.4.2 → system_diff-0.4.3}/mods/system-diff/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "system-diff",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "A pane beside the chat: what Claude is working on in your system, zoomed in, what just happened and why it matters, and a topic to learn (system-diff)",
   "types": "./types/index.d.ts",
   "author": {

{system_diff-0.4.2 → system_diff-0.4.3}/mods/system-diff/hooks/register.tsx

@@ -14,7 +14,7 @@ import type { Act, Page, Row } from '../types'
 // green what is new, done or to learn, white what to read, gray the background, red only what was taken away.
 
 const PANE = 'system-diff'
-const VERSION = '0.4.2' // the plugin's own, as .claude-plugin/plugin.json says (a test keeps them one)
+const VERSION = '0.4.3' // the plugin's own, as .claude-plugin/plugin.json says (a test keeps them one)
 const WIDEST = 999 // as wide as Claude Code docks a pane: 45% of the terminal
 const COMMANDS = ['system-diff', 'system-diff-pane'] as const
 const VIEWS = [['now', 'Now', 'n'], ['map', 'Map', 'm'], ['agents', 'Agents', 'a'], ['changes', 'Changes', 'c'],

{system_diff-0.4.2 → system_diff-0.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "system-diff"
-version = "0.4.2"
+version = "0.4.3"
 description = "Draws your system from its code (parts, entry points, data, outside systems) and what each change adds, changes or removes. No dependencies; SVG pictures for PRs and READMEs."
 readme = "README.md"
 license = "MIT"

{system_diff-0.4.2 → system_diff-0.4.3}/src/system_diff/__init__.py

@@ -5,4 +5,4 @@
     bp = extract.extract(DirSource(Path(".")), cfg)
     svg = graph.system_svg(bp, cfg)
 """
-__version__ = "0.4.2"
+__version__ = "0.4.3"

{system_diff-0.4.2 → system_diff-0.4.3}/src/system_diff/agent.py

@@ -137,30 +137,36 @@ def on_prompt(root: Path, payload: Dict[str, Any]) -> Optional[Dict[str, str]]:
 
 
 def on_tool(root: Path, payload: Dict[str, Any]) -> Optional[Dict[str, str]]:
-    """Note the file and keep a brief of its part for the status line. After an edit to code, look at what the turn
-    has done to the system so far, and say what this edit added to it (one hook at a time: they can overlap)."""
+    """After every tool: hand the agent what other agents published since its last tool. For a read or an edit of
+    a file in a part, also note the file and keep a brief of its part for the status line; after an edit to code,
+    look at what the turn has done to the system so far, and say what this edit added to it (one hook at a time:
+    they can overlap)."""
     tool = payload.get("tool_name", "")
+    agent_id = payload.get("agent_id") or ""
+
+    def unread() -> Dict[str, Any]:
+        return {"message": None, "context": agents.deliver(root, agent_id)}
+
     if tool not in EDIT_TOOLS + READ_TOOLS:
-        return None
+        return unread()
     given = payload.get("tool_input") or {}
     path = activity.relative(root, given.get("file_path") or given.get("notebook_path") or "")
     if not path:
-        return None
+        return unread()
     edit = tool in EDIT_TOOLS
-    agent_id = payload.get("agent_id") or ""
     activity.record(root, {"event": activity.EDIT if edit else activity.READ, "path": path, "tool": tool,
                            "session": payload.get("session_id", ""), "agent": agent_id})
     cfg = config.lenient(root)
     part = activity.part_of(path, Code(cfg))
     if part is None:
-        return None
+        return unread()
     if not activity.load_brief(root, part, max_age=600):
         activity.save_brief(root, learn.brief(root, cfg, part))
     if not (edit and turn_sha(root)):
-        return None
+        return unread()
     with activity.only_one(root, wait=10) as mine:
         if not mine:
-            return None
+            return unread()
         last = activity.read_state(root).get("turn") or {}
         before = last.get("told") or [s["text"] for s in last.get("story") or []]
         since, turn = compare_worktree(root, ["checkpoint", "turn"])
@@ -246,12 +252,12 @@ HOOKS = (  # event, matcher, how it runs, what it does
      "WezTerm, kitty, Windows Terminal)"),
     ("UserPromptSubmit", None, {"timeout": 10},
      "marks where each turn starts, and asks Claude to plan the work for a team of agents"),
-    ("PostToolUse", "|".join(READ_TOOLS), {"async": True},
-     "notes the files Claude reads, for the terminal view and the status line (in the background)"),
-    # Not in the background: only a hook Claude Code waits for can show you a line in the conversation. A timeout
-    # (seconds) so a stuck git never holds up the agent; Claude Code's own default is 600.
-    ("PostToolUse", "|".join(EDIT_TOOLS), {"timeout": 15},
-     "after an edit that changes the system's structure, one line on what it changed and why it matters"),
+    # One entry for every tool, and not in the background: only a hook Claude Code waits for can show you a line in
+    # the conversation or hand the agent its messages. A timeout (seconds) so a stuck git never holds up the agent;
+    # Claude Code's own default is 600.
+    ("PostToolUse", None, {"timeout": 15},
+     "notes the files Claude reads and, after an edit that changes the system's structure, one line on what it "
+     "changed; and hands each agent what other agents published"),
     ("Stop", None, {"timeout": 30}, "after each turn, one line on what the turn changed in the system"),
 )
 

{system_diff-0.4.2 → system_diff-0.4.3}/src/system_diff/agents.py

@@ -2,7 +2,7 @@
 CLAIMS, so agents keep to their own blocks; and a BUS, an async publish/subscribe channel whose topics are the system's
 blocks: an agent subscribes to the blocks its own depend on, every structural change to a block is published on that
 block's topic (by the hooks, as it happens), agents publish their own notes too, and each agent's unread messages
-reach it with its next tool call, without waiting on anyone.
+reach it with its next tool result of any kind, without waiting on anyone.
 
 Who is who: Claude Code names each subagent by an id (`agent_id` in its hook events; the main conversation has none,
 "main" here). A plan names agents by area ("billing"); an id is tied to a name when it first edits a block that name
@@ -65,6 +65,10 @@ def tie(root: Path, agent_id: str, name: str) -> None:
         data = _load(root)
         if data["ids"].get(agent_id) != name:
             data["ids"][agent_id] = name
+            short = data["agents"].get("agent-" + agent_id[:6])   # what it read before it had a name stays read
+            if short:
+                a = _agent(data, name)
+                a["read"] = max(a["read"], short["read"])
             _save(root, data)
 
 
@@ -163,6 +167,20 @@ def as_context(msgs: List[Dict[str, Any]], most: int = 8) -> str:
 
 # ── what the hooks do for each agent ─────────────────────────────────────────
 
+def _for_context(msgs: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """The messages worth putting in an agent's context: spread warnings reach the agent they are about directly; on
+    the bus they are a record for the inbox tool."""
+    return [m for m in msgs if not (m.get("from") == SYSTEM and m.get("kind") == "warning")]
+
+
+def deliver(root: Path, agent_id: str) -> str:
+    """The unread messages for the agent with this Claude Code id ("" or "main": the main conversation), as context
+    text, marked read; "" without writing anything when there is no bus yet."""
+    if not (git_dir(root) / BUS).exists():
+        return ""
+    return as_context(_for_context(inbox(root, name_of(root, agent_id))))
+
+
 def after_edit(root: Path, agent_id: str, part: Optional[str], notes: List[Dict[str, Any]], bp: dict) -> Dict[str, str]:
     """After an agent's edit: tie it to a plan name if it edited a claimed block nobody else is tied to, subscribe it
     to its block and the blocks that block depends on, publish what the edit changed in the structure on the topics
@@ -186,8 +204,7 @@ def after_edit(root: Path, agent_id: str, part: Optional[str], notes: List[Dict[
         publish(root, f"agent:{claimed}", f"{name} edited your block {part}", sender=name, kind="warning")
     from . import config
     wide = spread(root, name, agent_id, bp, config.lenient(root))
-    # spread warnings reach the agent they are about directly; on the bus they are a record for the inbox tool
-    unread = [m for m in inbox(root, name) if not (m.get("from") == SYSTEM and m.get("kind") == "warning")]
+    unread = _for_context(inbox(root, name))
     context = "\n".join(t for t in (as_context(unread), wide) if t)
     warn = "; ".join(t for t in (warn, wide) if t)
     return {"context": context, "warn": warn, "name": name}

{system_diff-0.4.2 → system_diff-0.4.3}/tests/test_design_and_pane.py

@@ -270,6 +270,31 @@ def test_the_agents_tab_shows_each_agent_and_warns_when_two_edit_one_block(repo,
     assert "● API  @api @st" in "\n".join(text)               # who works where, on the diagram
 
 
+def test_messages_reach_an_agent_with_its_next_tool_result_of_any_kind_once(repo):
+    from system_diff import agent, agents
+    from system_diff.sources import git_dir
+
+    def tool(name, **given):
+        said: list = []
+        agent.run_hook(json.dumps({"cwd": str(repo), "hook_event_name": "PostToolUse", "tool_name": name,
+                                   "agent_id": "a1", "tool_input": given}), emit=said.append)
+        return [json.loads(s) for s in said]
+
+    bus = git_dir(repo) / agents.BUS
+    assert not bus.exists() and tool("Bash", command="ls") == []      # no bus: nothing said, nothing written
+    assert not bus.exists()
+    agents.tie(repo, "a1", "api")
+    agents.publish(repo, "agent:api", "please keep GET /api/orders", sender="web")
+    out = tool("Bash", command="ls")                                  # not a file tool: it still gets it
+    assert "web on agent:api: please keep GET /api/orders" in out[0]["hookSpecificOutput"]["additionalContext"]
+    assert out[0]["hookSpecificOutput"]["hookEventName"] == "PostToolUse"
+    assert tool("Bash", command="ls") == []                           # once only
+    agents.publish(repo, "agent:api", "store moved to app/db", sender="store")
+    out = tool("Read", file_path=str(repo / "app/core/rules.py"))
+    assert "store on agent:api: store moved to app/db" in out[0]["hookSpecificOutput"]["additionalContext"]
+    assert tool("Read", file_path=str(repo / "app/core/rules.py")) == []
+
+
 def test_one_agent_editing_two_areas_in_a_turn_is_told_once_to_plan_a_team(repo, files):
     from system_diff import agent
 
@@ -316,3 +341,11 @@ def test_a_narrow_pane_gets_compact_diagrams_unless_asked_otherwise(repo, capsys
 def _run(capsys, repo, *args):
     assert main(["--repo", str(repo), "panel", "--protocol", "2", *args]) == 0
     return capsys.readouterr().out
+
+
+def test_what_an_agent_read_before_it_had_a_name_stays_read(repo):
+    from system_diff import agents
+    agents.publish(repo, "all", "hello", sender="main")
+    assert len(agents.inbox(repo, "agent-a1b2c3")) == 1
+    agents.tie(repo, "a1b2c3d4", "api")
+    assert agents.inbox(repo, "api") == []

{system_diff-0.4.2 → system_diff-0.4.3}/tests/test_terminal_and_learning.py

@@ -332,10 +332,8 @@ def test_setup_wires_three_hooks_and_a_status_line_and_leaves_someone_elses_alon
     agent.setup_claude(repo, "local", out=said.append)
     path = repo / ".claude" / "settings.local.json"
     data = json.loads(path.read_text())
-    assert data["hooks"]["PostToolUse"] == [   # reads noted in the background; an edit waited for, so it can speak
-        {"matcher": "Read", "hooks": [{"type": "command", "command": "system-diff hook", "async": True}]},
-        {"matcher": "Edit|Write|MultiEdit|NotebookEdit", "hooks": [
-            {"type": "command", "command": "system-diff hook", "timeout": 15}]}]
+    assert data["hooks"]["PostToolUse"] == [   # every tool, waited for: it can speak and hand over messages
+        {"hooks": [{"type": "command", "command": "system-diff hook", "timeout": 15}]}]
     assert data["hooks"]["UserPromptSubmit"][0]["hooks"][0]["timeout"] == 10   # waited for: it tells Claude
     assert data["statusLine"] == {"type": "command", "command": "system-diff statusline"}
     agent.setup_claude(repo, "local", undo=True, out=said.append)
@@ -347,11 +345,25 @@ def test_setup_wires_three_hooks_and_a_status_line_and_leaves_someone_elses_alon
     said.clear()
     agent.setup_claude(repo, "local", out=said.append)
     post = json.loads(path.read_text())["hooks"]["PostToolUse"]
-    assert post[0] == {"hooks": [{"command": "mine"}]} and [e["matcher"] for e in post[1:]] == [
-        "Read", "Edit|Write|MultiEdit|NotebookEdit"]
+    assert post == [{"hooks": [{"command": "mine"}]},
+                    {"hooks": [{"type": "command", "command": "system-diff hook", "timeout": 15}]}]
     assert any(s.startswith("updated the PostToolUse hook") for s in said)
     agent.setup_claude(repo, "local", undo=True, out=said.append)
 
+    two = {"hooks": {"PostToolUse": [   # the two entries the setup before this one wrote
+        {"matcher": "Read", "hooks": [{"type": "command", "command": "system-diff hook", "async": True}]},
+        {"matcher": "Edit|Write|MultiEdit|NotebookEdit", "hooks": [
+            {"type": "command", "command": "system-diff hook", "timeout": 15}]}]}}
+    path.write_text(json.dumps(two))
+    said.clear()
+    agent.setup_claude(repo, "local", out=said.append)
+    assert json.loads(path.read_text())["hooks"]["PostToolUse"] == [
+        {"hooks": [{"type": "command", "command": "system-diff hook", "timeout": 15}]}]   # one, not three
+    assert sum(s.startswith("updated the PostToolUse hook") for s in said) == 1
+    agent.setup_claude(repo, "local", out=said.append)
+    assert len(json.loads(path.read_text())["hooks"]["PostToolUse"]) == 1                 # and it stays one
+    agent.setup_claude(repo, "local", undo=True, out=said.append)
+
     user = home / ".claude" / "settings.json"
     user.parent.mkdir(parents=True)
     user.write_text(json.dumps({"statusLine": {"type": "command", "command": "my-line"}}))