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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: system-diff
-Version: 0.4.0
+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
@@ -92,6 +92,8 @@ Claude is changing in it. `/system-diff close` (or "× close" in its tab row) hi
     - **Zoom:** Enter (or a second click) zooms in on a container's components, with the lines between them. `b` goes
       back, `f` follows Claude again.
     - **Scroll:** `[` `]` scroll a wide diagram across; shift ↑ ↓, Page Up/Down or the wheel scroll a tall one.
+    - **Zoom:** ⊖ and ⊕ in the tab row (or `-` and `=`) draw the diagrams compact (narrower boxes, no flow labels) or
+      tiny (titles only), to fit more of the system in a narrow pane; below 110 columns it is compact by itself.
   - **This turn**: each change to the design, and what it trades off.
   - **Learn**: how the part Claude works on is designed.
     - The principle its place calls for: an edge of the system, an adapter, a shared foundation, a coordinator.
@@ -130,10 +132,12 @@ 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
+  turn, the edit hook tells it, once that turn, to plan a team with `plan_agents` and hand the rest to agents.
 
 The MCP tools: `plan_agents`, `claim`, `publish`, `subscribe`, `inbox`, `team`. It all stays in `.git/system-diff/`
 (`agents.json`, `bus.jsonl`), never pushed.
@@ -142,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.0 → system_diff-0.4.3}/README.md

@@ -60,6 +60,8 @@ Claude is changing in it. `/system-diff close` (or "× close" in its tab row) hi
     - **Zoom:** Enter (or a second click) zooms in on a container's components, with the lines between them. `b` goes
       back, `f` follows Claude again.
     - **Scroll:** `[` `]` scroll a wide diagram across; shift ↑ ↓, Page Up/Down or the wheel scroll a tall one.
+    - **Zoom:** ⊖ and ⊕ in the tab row (or `-` and `=`) draw the diagrams compact (narrower boxes, no flow labels) or
+      tiny (titles only), to fit more of the system in a narrow pane; below 110 columns it is compact by itself.
   - **This turn**: each change to the design, and what it trades off.
   - **Learn**: how the part Claude works on is designed.
     - The principle its place calls for: an edge of the system, an adapter, a shared foundation, a coordinator.
@@ -98,10 +100,12 @@ 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
+  turn, the edit hook tells it, once that turn, to plan a team with `plan_agents` and hand the rest to agents.
 
 The MCP tools: `plan_agents`, `claim`, `publish`, `subscribe`, `inbox`, `team`. It all stays in `.git/system-diff/`
 (`agents.json`, `bus.jsonl`), never pushed.
@@ -110,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.0 → 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.0 → 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.0 → system_diff-0.4.3}/mods/system-diff/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "system-diff",
-  "version": "0.4.0",
+  "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.0 → system_diff-0.4.3}/mods/system-diff/hooks/page.tsx

@@ -12,7 +12,7 @@ import type { Page, PageBlock, Row, Run } from '../types'
 // the rest keeps its colours: yellow what changed, green what is new, red what went, gray the background.
 
 type Props = { page: Page; canGoBack: boolean }
-type State = { sel: string; sx: number; mine: boolean; ticking?: boolean }
+type State = { sel: string; sx: number; mine: boolean; ticking?: boolean; free?: boolean } // free: scrolled by hand
 
 const COLORS: Record<string, string> = {
   accent: 'blue', focus: 'blue', near: 'blue', data: 'blue',
@@ -88,7 +88,7 @@ const PageView: ClientModule<JsonValue, State> = (raw, surface) => {
   const state = surface.state
   const sel = state?.mine && byId.has(state.sel) ? state.sel : byId.has(page.pick) ? page.pick : (page.blocks[0]?.id ?? '')
   const picked = byId.get(sel)
-  const sx = across(page, cols, state?.mine ? state.sx : 0, picked)
+  const sx = across(page, cols, state?.mine ? state.sx : 0, state?.free ? undefined : picked)
 
   // The pane was laid out for another width (the split moved): ask for this one once it holds, not for every
   // width a drag passes on its way.
@@ -104,7 +104,8 @@ const PageView: ClientModule<JsonValue, State> = (raw, surface) => {
         surface.post({ width: askedWidth })
       }
     })
-    surface.setState({ sel: state?.sel ?? '', sx: state?.sx ?? 0, mine: state?.mine ?? false, ticking: true })
+    surface.setState({ sel: state?.sel ?? '', sx: state?.sx ?? 0, mine: state?.mine ?? false, ticking: true,
+                       free: state?.free })
   }
 
   const pick = (b: PageBlock | undefined, x = sx) => {
@@ -127,8 +128,10 @@ const PageView: ClientModule<JsonValue, State> = (raw, surface) => {
     } else if (['up', 'down', 'left', 'right'].includes(e.key)) {
       pick(move(page.blocks, picked, e.key))
     } else if (e.key === '[' || e.key === ']') {
-      surface.setState({ sel, sx: across(page, cols, sx + (e.key === '[' ? -STEP : STEP), undefined), mine: true,
+      surface.setState({ sel, sx: across(page, cols, sx + (e.key === '[' ? -STEP : STEP), undefined), mine: true, free: true,
                          ticking: true })
+    } else if (e.key === '-' || e.key === '=' || e.key === '+') {
+      surface.post({ zoomBy: e.key === '-' ? 1 : -1 }) // - shows more of the system, = bigger boxes
     } else if (e.key === 'return') {
       act(picked, 'enter')
     } else if (e.key === ' ') {

{system_diff-0.4.0 → system_diff-0.4.3}/mods/system-diff/hooks/pane.test.tsx

@@ -185,3 +185,15 @@ test('/system-diff close closes the pane, and so does its close button', async (
   expect(closed).toEqual(['system-diff', 'system-diff'])
   await ui.unmount()
 })
+
+test('zoom out draws the diagrams compact, zoom in full again', async ($, on) => {
+  const asked: string[][] = []
+  answer(on, asked)
+  await $.command.run(RUN)
+  const ui = await $.ui.mount({ ...PANE, surface: 'terminal' })
+  await ui.press({ key: 'zoom-out' })
+  expect(asked[asked.length - 1]?.join(' ')).toContain('--zoom 1')
+  await ui.key({ key: '=', in: 'page' })
+  expect(asked[asked.length - 1]?.join(' ')).toContain('--zoom 0')
+  await ui.unmount()
+})

{system_diff-0.4.0 → 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.0' // 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'],
@@ -25,6 +25,9 @@ const view = atom({ plugin: 'system-diff', key: 'view' } as const, 'now', { shap
 const part = atom({ plugin: 'system-diff', key: 'part' } as const, '', { shape: 'part-1' })
 const back = atom({ plugin: 'system-diff', key: 'back' } as const, [] as string[], { shape: 'back-2' })
 const note = atom({ plugin: 'system-diff', key: 'note' } as const, 'Reading the system…', { shape: 'note-1' })
+// How compact the diagrams are: -1 by the pane's width (compact below 110 columns), 0 full, 1 compact, 2 tiny.
+const zoomLevel = atom({ plugin: 'system-diff', key: 'zoom' } as const, -1, { shape: 'zoom-1' })
+const ZOOM_WORD = ['full', 'compact', 'tiny']
 
 // How to run system-diff: the repository's own virtualenv first, then whatever is on PATH.
 const RUNNERS: string[][] = [
@@ -73,6 +76,8 @@ async function refresh($: EngineInterface): Promise<void> {
       again = false
       const argv = ['panel', '--protocol', '2', '--width', String(columns), '--view', await read($, view),
                     '--part', await read($, part)]
+      const level = await read($, zoomLevel)
+      if (level >= 0) argv.push('--zoom', String(level)) // left out, the engine picks by the width (older ones too)
       const got = await run($, argv)
       if (got && !got.old) {
         if (got.out !== last) {
@@ -155,6 +160,13 @@ async function scrollBy($: EngineInterface, rows: number): Promise<void> {
 
 // As wide as Claude Code docks a pane, the first time: a width the person set (dragged, or with the pane's keys:
 // ctrl+x ← →) is theirs from then on.
+// More of the system in the pane (zoom out, +1) or bigger boxes (zoom in, -1), from where the page is drawn now.
+async function zoomBy($: EngineInterface, by: number): Promise<void> {
+  const drawnAt = (await read($, page))?.zoom ?? 0
+  await update($, zoomLevel, () => Math.max(0, Math.min(2, drawnAt + by)))
+  await refresh($)
+}
+
 function open($: EngineInterface) {
   return $.ui.open({ id: PANE, title: 'System diff', columns: WIDEST })
 }
@@ -213,7 +225,7 @@ export const register: Register = on => {
   // What the page (page.tsx) asks for.
   on('ui.message', { component: 'Pane', requestId: PANE }, async ($, e) => {
     const data = (e.data ?? {}) as Act & { back?: boolean; follow?: boolean; width?: number; reveal?: number;
-                                             scrollBy?: number }
+                                             scrollBy?: number; zoomBy?: number }
     if (typeof data.width === 'number' && data.width > 0 && data.width !== columns) {
       columns = data.width
       await refresh($)
@@ -223,6 +235,7 @@ export const register: Register = on => {
     else if (typeof data.learn === 'string') await learn($, data.learn)
     else if (data.back) await goBack($)
     else if (data.follow) await follow($)
+    else if (typeof data.zoomBy === 'number') await zoomBy($, data.zoomBy)
     else if (typeof data.view === 'string') await choose($, data.view)
     return {}
   })
@@ -278,11 +291,14 @@ export const register: Register = on => {
           {behind.length > 0 && (
             <Button key="back" hotkey="b" plain onPress={() => void goBack($)}><Text dimColor>← Back</Text></Button>
           )}
+          <Button key="zoom-out" plain onPress={() => void zoomBy($, 1)}><Text dimColor>⊖</Text></Button>
+          <Text dimColor>{ZOOM_WORD[drawn?.zoom ?? 0] ?? 'full'}</Text>
+          <Button key="zoom-in" plain onPress={() => void zoomBy($, -1)}><Text dimColor>⊕</Text></Button>
           <Button key="close" plain onPress={() => void $.ui.close({ id: PANE })}><Text dimColor>× close</Text></Button>
         </Box>
         {said !== '' && <Text dimColor>{said}</Text>}
         {drawn !== null && Client !== undefined && (
-          <Client key="page" module="./page.tsx" props={{ page: drawn, canGoBack: behind.length > 0 }} />
+          <Client key="page" module="./page.tsx" width="100%" props={{ page: drawn, canGoBack: behind.length > 0 }} />
         )}
         {drawn !== null && Client === undefined && drawn.rows.map(line)}
         {drawn !== null && Client === undefined && (

{system_diff-0.4.0 → system_diff-0.4.3}/mods/system-diff/types/index.d.ts

@@ -24,6 +24,7 @@ export type Page = {
   lights: Record<string, string[]>
   details: Record<string, Row[]>
   pick: string
+  zoom?: number // how compact it is drawn: 0 full, 1 compact, 2 tiny
 }
 
 declare module 'claude-code' {
@@ -34,6 +35,7 @@ declare module 'claude-code' {
       part: Shaped<string>
       back: Shaped<string[]>
       note: Shaped<string>
+      zoom: Shaped<number>
     }
   }
 }

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "system-diff"
-version = "0.4.0"
+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.0 → 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.0"
+__version__ = "0.4.3"

{system_diff-0.4.0 → 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.0 → 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
@@ -24,6 +24,7 @@ from .sources import git_dir
 
 STATE, BUS = "agents.json", "bus.jsonl"
 MAIN = "main"
+SYSTEM = "system-diff"   # the sender of what system-diff itself publishes
 KEEP = 2000        # messages kept on the bus
 MOST_AGENTS = 4    # a plan's agents at most, unless asked for more
 
@@ -33,10 +34,11 @@ def _load(root: Path) -> Dict[str, Any]:
         data = json.loads((git_dir(root) / STATE).read_text(encoding="utf-8"))
         if isinstance(data, dict):
             return {"plan": data.get("plan") or {}, "claims": data.get("claims") or {},
-                    "agents": data.get("agents") or {}, "ids": data.get("ids") or {}}
+                    "agents": data.get("agents") or {}, "ids": data.get("ids") or {},
+                    "warned": data.get("warned") or {}}
     except (OSError, ValueError):
         pass
-    return {"plan": {}, "claims": {}, "agents": {}, "ids": {}}
+    return {"plan": {}, "claims": {}, "agents": {}, "ids": {}, "warned": {}}
 
 
 def _save(root: Path, data: Dict[str, Any]) -> None:
@@ -63,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)
 
 
@@ -161,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
@@ -182,7 +202,59 @@ def after_edit(root: Path, agent_id: str, part: Optional[str], notes: List[Dict[
     if part and claimed and claimed != name:
         warn = f"{part} is claimed by agent {claimed}; {name} just edited it"
         publish(root, f"agent:{claimed}", f"{name} edited your block {part}", sender=name, kind="warning")
-    return {"context": as_context(inbox(root, name)), "warn": warn, "name": name}
+    from . import config
+    wide = spread(root, name, agent_id, bp, config.lenient(root))
+    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}
+
+
+def areas_of(root: Path, bp: dict, cfg: Dict[str, Any]) -> Dict[str, str]:
+    """Each block's area: the agent the saved plan gave it to, when there is a plan; else its container, or the
+    block itself when it is in none."""
+    agents = (_load(root)["plan"] or {}).get("agents") or []
+    if agents:
+        return {b: g["name"] for g in agents for b in g.get("blocks") or []}
+    from .architecture import groups_of
+    group = groups_of(bp, cfg, design.kinds(bp, cfg))
+    return {cid: (group[cid][2:] if group.get(cid, "").startswith("g:") else cid) for cid in bp["components"]}
+
+
+def spread(root: Path, name: str, agent_id: str, bp: dict, cfg: Dict[str, Any]) -> str:
+    """When one agent has edited blocks in two or more areas this turn: a message telling it to plan a team and hand
+    the rest on, once per agent per turn (also published to all); else ""."""
+    from .extract import Code
+    code = Code(cfg)
+    me = "" if agent_id in ("", None, MAIN) else agent_id
+    start, parts = 0.0, []
+    for e in activity.events(root, 400):
+        if e.get("event") == activity.PROMPT and not activity.is_system(e.get("text", "")):
+            start, parts = e["at"], []
+        elif e.get("event") == activity.EDIT and (e.get("agent") or "") == me and e.get("path"):
+            part = activity.part_of(e["path"], code)
+            if part and part not in parts:
+                parts.append(part)
+    area = areas_of(root, bp, cfg)
+    seen: List[str] = []
+    for p in parts:
+        a = area.get(p, p)
+        if a not in seen:
+            seen.append(a)
+    if len(seen) < 2:
+        return ""
+    data = _load(root)
+    turn = str(start)
+    told = data["warned"].get(turn) or []
+    if name in told:
+        return ""
+    data["warned"] = {turn: told + [name]}   # only the latest turn is kept
+    _save(root, data)
+    text = (f"{name} has edited blocks in {len(seen)} areas this turn ({', '.join(seen)}). system-diff runs work "
+            "that spans areas as a team: call plan_agents with what is left, launch its agents in parallel, and "
+            "keep to one area yourself.")
+    publish(root, "all", text, sender=SYSTEM, kind="warning")
+    return text
 
 
 def who_worked(events: Iterable[dict], code) -> Dict[str, Dict[str, Any]]:

{system_diff-0.4.0 → system_diff-0.4.3}/src/system_diff/canvas.py

@@ -138,8 +138,12 @@ def title_style(n: dict) -> str:
     return f"title bold {st}" if st != "same" else "title"
 
 
+ZOOMS = {0: (20, 32, 2, 6, 4), 1: (12, 22, 0, 5, 3), 2: (8, 16, 0, 5, 3)}  # min box, max box, rows, channel, gap
+                                                                         # by zoom: full, compact, tiny
+
+
 def layered(nodes: List[dict], edges: List[dict], columns: List[Sequence[str]], *, width: int = 100,
-            centre: bool = False, most_lines: int = 2) -> Grid:
+            centre: bool = False, most_lines: int = 2, zoom: int = 0) -> Grid:
     """A system diagram: `nodes` (id, col, title, sub, status, type: actor|component|group|store|host; `agent` where
     the agent works, `focus` for the box zoomed in on, `items` for the components a container holds, `lines` for
     rows inside a box) in `columns` order, joined by `edges` (from, to, kind, status, label; `from_item`/`to_item`:
@@ -150,6 +154,12 @@ def layered(nodes: List[dict], edges: List[dict], columns: List[Sequence[str]],
     present = [k for k, _h in columns if any(n["col"] == k for n in nodes)]
     if not present:
         return g
+    least, most_w, rows_in, chan_min, chan_pad = ZOOMS.get(zoom, ZOOMS[0])
+    most_lines = min(most_lines, rows_in)
+    if zoom:   # compact: no labels on flows (a picked box's detail names them), tiny: no subtitles either
+        edges = [{**e, "label": ""} for e in edges]
+        if zoom >= 2:
+            nodes = [{**n, "sub": ""} for n in nodes]
     heading = {k: h for k, h in columns}
     ci = {k: i for i, k in enumerate(present)}
     col_nodes = [[n for n in nodes if n["col"] == k] for k in present]
@@ -181,13 +191,13 @@ def layered(nodes: List[dict], edges: List[dict], columns: List[Sequence[str]],
     item_row = {it["id"]: (n["id"], 3 + j) for n in nodes for j, it in enumerate(n.get("items") or [])}
 
     # widths: as wide as the longest row wants, narrowed together when the whole is wider than the pane
-    want = [min(32, max([len(t) + 4 for n in col for t, _s, _b in contents[n["id"]][:1]]
-                        + [len(t) + 4 for n in col for t, _s, _b in contents[n["id"]][2:]]
-                        + [len(heading[present[i]]) + 1, 14]))
+    want = [min(most_w, max([len(t) + 4 for n in col for t, _s, _b in contents[n["id"]][:1]]
+                            + [len(t) + 4 for n in col for t, _s, _b in contents[n["id"]][2:]]
+                            + [min(len(heading[present[i]]) + 1, most_w), least]))
             for i, col in enumerate(col_nodes)]
     label_w = max([len(e.get("label") or "") for e in edges] + [0])
-    gaps = (8 + label_w) * len(present)
-    while sum(want) + gaps > width and max(want) > 20:
+    gaps = (chan_min + 2 + label_w) * len(present)
+    while sum(want) + gaps > width and max(want) > least:
         biggest = max(range(len(want)), key=lambda i: want[i])
         want[biggest] -= 1
     heights = {n["id"]: 2 + len(contents[n["id"]]) for n in nodes}
@@ -320,7 +330,7 @@ def layered(nodes: List[dict], edges: List[dict], columns: List[Sequence[str]],
         if e.get("label") and cs != ct:
             label_in[hops[-1][0]] = max(label_in[hops[-1][0]], len(e["label"]) + 2)
     widths = want
-    chan = [max(6, len(lanes[k]) + 4 + label_in[k]) for k in range(len(present))]
+    chan = [max(chan_min, len(lanes[k]) + chan_pad + label_in[k]) for k in range(len(present))]
     if not lanes[len(present) - 1]:
         chan[-1] = 0
     xs, x = [], 0

{system_diff-0.4.0 → system_diff-0.4.3}/src/system_diff/cli.py

@@ -195,6 +195,7 @@ def parser() -> argparse.ArgumentParser:
     pn.add_argument("--width", type=int, default=80)
     pn.add_argument("--view", default="now", choices=["now", "map", "changes", "topics", "agents"])
     pn.add_argument("--part", default="", help="the part to zoom in on (default: the one the agent works on)")
+    pn.add_argument("--zoom", type=int, default=-1, help="diagrams 0 full, 1 compact, 2 tiny; -1 by the width")
     pn.add_argument("--protocol", type=int, default=1, help="2: a page of runs and pickable blocks (the mod's painter)")
     pf = sub.add_parser("profile", help="what you want explained: technologies marked new to you")
     pf.add_argument("--learn", metavar="TECH", help="mark a technology new to you, or unmark it")
@@ -254,7 +255,7 @@ def main(argv: Optional[List[str]] = None) -> int:
         return agent.run_hook(sys.stdin.read() if not sys.stdin.isatty() else "")
     if args.cmd == "panel":
         from . import panel
-        return panel.main(root, args.width, args.view, args.part, args.protocol)
+        return panel.main(root, args.width, args.view, args.part, args.protocol, args.zoom)
     if args.cmd == "profile":
         from . import profile
         if args.learn:

{system_diff-0.4.0 → system_diff-0.4.3}/src/system_diff/pane.py

@@ -35,7 +35,7 @@ def _name(nid: str, *bps: dict) -> str:
 def _diagram(page: canvas.Page, c, model: Dict[str, Any], width: int, centre: bool = False) -> canvas.Grid:
     """The diagram on the page, every box a block: Enter zooms in on it; its detail says what it uses and what uses
     it, all of it (the diagram draws each box's main flows)."""
-    g = canvas.layered(model["nodes"], model["edges"], model["columns"], width=width, centre=centre)
+    g = canvas.layered(model["nodes"], model["edges"], model["columns"], width=width, centre=centre, zoom=ZOOM)
     conns = graph.connections(c.after)
     names = {n["id"]: n["title"] for n in model["nodes"]}
     names.update({i["id"]: i["title"] for n in model["nodes"] for i in n.get("items") or []})
@@ -476,7 +476,19 @@ def view_agents(root: Path, width: int) -> Dict[str, Any]:
     return page.json(view="agents", part="")
 
 
-def show(root: Path, width: int = 80, view: str = "now", part: Optional[str] = None) -> Dict[str, Any]:
+ZOOM = 0   # how compact the diagrams are drawn: 0 full, 1 compact, 2 tiny (show sets it)
+
+
+def show(root: Path, width: int = 80, view: str = "now", part: Optional[str] = None, zoom: int = -1) -> Dict[str, Any]:
+    """The page for a view. `zoom` -1: compact below 110 columns, full above."""
+    global ZOOM
+    ZOOM = (1 if width < 110 else 0) if zoom < 0 else max(0, min(2, zoom))
+    out = _show(root, width, view, part)
+    out["zoom"] = ZOOM
+    return out
+
+
+def _show(root: Path, width: int = 80, view: str = "now", part: Optional[str] = None) -> Dict[str, Any]:
     if view == "agents":
         return view_agents(root, width)
     if view == "map":

{system_diff-0.4.0 → system_diff-0.4.3}/src/system_diff/panel.py

@@ -232,10 +232,11 @@ def rows(root: Path, width: int = 80) -> List[textmap.Line]:
     return got["head"] + got["rows"]
 
 
-def main(root: Path, width: int, view: str = "now", part: Optional[str] = None, protocol: int = 1) -> int:
+def main(root: Path, width: int, view: str = "now", part: Optional[str] = None, protocol: int = 1,
+         zoom: int = -1) -> int:
     if protocol >= 2:
         from . import pane
-        print(json.dumps(pane.show(root, width, view, part or None), ensure_ascii=False))
+        print(json.dumps(pane.show(root, width, view, part or None, zoom), ensure_ascii=False))
         return 0
     got = show(root, width, view, part or None)
     for key in ("head", "rows"):

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

@@ -18,7 +18,7 @@ REFUND = ('from fastapi import APIRouter\nrouter = APIRouter()\n\n\n@router.post
 
 
 def page(capsys, repo, *args):
-    assert main(["--repo", str(repo), "panel", "--width", "100", "--protocol", "2", *args]) == 0
+    assert main(["--repo", str(repo), "panel", "--width", "100", "--protocol", "2", "--zoom", "0", *args]) == 0
     out = json.loads(capsys.readouterr().out)
     return out, ["".join(run[0] for run in row) for row in out["rows"]]
 
@@ -268,3 +268,84 @@ def test_the_agents_tab_shows_each_agent_and_warns_when_two_edit_one_block(repo,
     assert any(t.startswith("THE TEAM  plan: make the API") for t in text)
     assert any("api and store all edit API" in t for t in text)
     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
+
+    def prompt():
+        agent.run_hook(json.dumps({"cwd": str(repo), "hook_event_name": "UserPromptSubmit", "prompt": "go"}),
+                       emit=lambda _s: None)
+
+    def edit(path, text, **who):
+        files(repo, {path: text})
+        said: list = []
+        agent.run_hook(json.dumps({"cwd": str(repo), "hook_event_name": "PostToolUse", "tool_name": "Edit", **who,
+                                   "tool_input": {"file_path": str(repo / path)}}), emit=said.append)
+        outs = [json.loads(s) for s in said]
+        warns = " ".join(o.get("systemMessage", "") for o in outs)
+        context = " ".join(o.get("hookSpecificOutput", {}).get("additionalContext", "") for o in outs)
+        return warns, context
+
+    routes, rules = "app/api/routes.py", "app/core/rules.py"
+    prompt()
+    warns, context = edit(routes, (repo / routes).read_text() + "\n# one\n")
+    assert "areas this turn" not in warns + context              # one area so far
+    warns, context = edit(rules, (repo / rules).read_text() + "\n# one\n")
+    assert "main has edited blocks in 2 areas this turn" in warns and "plan_agents" in warns
+    assert "main has edited blocks in 2 areas this turn" in context and "plan_agents" in context
+    warns, context = edit("app/db/repo.py", (repo / "app/db/repo.py").read_text() + "\n# one\n")
+    assert "areas this turn" not in warns + context              # once a turn
+    prompt()
+    edit(routes, (repo / routes).read_text() + "# two\n")
+    warns, context = edit(rules, (repo / rules).read_text() + "# two\n")
+    assert "areas this turn" in warns and "areas this turn" in context    # a new turn may warn again
+    prompt()
+    for text in ("# a\n", "# b\n"):                            # a subagent staying in its one area
+        warns, context = edit(routes, (repo / routes).read_text() + text, agent_id="a1")
+        assert "areas this turn" not in warns and "a1 has edited" not in context  # main's warning may reach it by bus
+
+
+def test_a_narrow_pane_gets_compact_diagrams_unless_asked_otherwise(repo, capsys):
+    narrow = json.loads(_run(capsys, repo, "--width", "90"))
+    wide = json.loads(_run(capsys, repo, "--width", "140"))
+    assert narrow["zoom"] == 1 and wide["zoom"] == 0
+    assert json.loads(_run(capsys, repo, "--width", "90", "--zoom", "2"))["zoom"] == 2
+
+
+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.0 → 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"}}))