symphony-code 0.0.1__tar.gz → 0.0.2__tar.gz

{symphony_code-0.0.1 → symphony_code-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: symphony-code
-Version: 0.0.1
+Version: 0.0.2
 Summary: Symphony coding agent: workspace tools, JSONL sessions, and a Textual TUI on top of symphony-harness (import as coding_agent; run as `symphony`)
 Author: Sarthak Chauhan
 Author-email: Sarthak Chauhan <sarthakchauhann@gmail.com>
@@ -27,15 +27,15 @@ Description-Content-Type: text/markdown
 
 Run an AI coding agent in your terminal, or import the coding-agent API from the Symphony workspace. Package import name: `coding_agent`.
 
-**Availability:** this package is not currently published on PyPI. To run it today, use a checkout of the repository:
+**Availability:** version 0.0.1 is on PyPI.
 
 ```sh
-git clone https://github.com/Sarthakischauhan/symphony.git
-cd symphony
-uv sync
-uv run --package symphony-code symphony --workspace /path/to/project
+python -m pip install symphony-code
+symphony --workspace /path/to/project
 ```
 
+To run the current `main` branch instead of the published release, clone the repository, run `uv sync`, then `uv run --package symphony-code symphony --workspace /path/to/project`.
+
 `symphony`, `symphony-code`, and `coding-agent-tui` are aliases for the same terminal application. Configure a provider on first launch, or set credentials beforehand. See the [installation guide](../docs/getting-started/installation.md) and [quickstart](../docs/getting-started/quickstart.md).
 
 ## Use the library
@@ -63,4 +63,10 @@ print(result.output_text)
 - [Sessions and resume](../docs/user-guide/sessions.md)
 - [Package API guide](../docs/packages/symphony-code.md)
 
-**Safety:** tools run with the current user's permissions; approval prompts do not sandbox commands or restrict paths. Read the [security policy](../SECURITY.md) before use.
+**Safety:** tools run with the current user's permissions; approval prompts do not sandbox commands or restrict paths. Read the [security policy](../SECURITY.md) before use.
+
+### Browser interface
+
+Run `symphony web --workspace /path/to/project` to launch Symphony Web. Installed
+wheels include the React frontend; Node.js is not needed by end users. See the
+[Web guide](../docs/developer-guide/web.md) for development and security details.

{symphony_code-0.0.1 → symphony_code-0.0.2}/README.md

@@ -2,15 +2,15 @@
 
 Run an AI coding agent in your terminal, or import the coding-agent API from the Symphony workspace. Package import name: `coding_agent`.
 
-**Availability:** this package is not currently published on PyPI. To run it today, use a checkout of the repository:
+**Availability:** version 0.0.1 is on PyPI.
 
 ```sh
-git clone https://github.com/Sarthakischauhan/symphony.git
-cd symphony
-uv sync
-uv run --package symphony-code symphony --workspace /path/to/project
+python -m pip install symphony-code
+symphony --workspace /path/to/project
 ```
 
+To run the current `main` branch instead of the published release, clone the repository, run `uv sync`, then `uv run --package symphony-code symphony --workspace /path/to/project`.
+
 `symphony`, `symphony-code`, and `coding-agent-tui` are aliases for the same terminal application. Configure a provider on first launch, or set credentials beforehand. See the [installation guide](../docs/getting-started/installation.md) and [quickstart](../docs/getting-started/quickstart.md).
 
 ## Use the library
@@ -38,4 +38,10 @@ print(result.output_text)
 - [Sessions and resume](../docs/user-guide/sessions.md)
 - [Package API guide](../docs/packages/symphony-code.md)
 
-**Safety:** tools run with the current user's permissions; approval prompts do not sandbox commands or restrict paths. Read the [security policy](../SECURITY.md) before use.
+**Safety:** tools run with the current user's permissions; approval prompts do not sandbox commands or restrict paths. Read the [security policy](../SECURITY.md) before use.
+
+### Browser interface
+
+Run `symphony web --workspace /path/to/project` to launch Symphony Web. Installed
+wheels include the React frontend; Node.js is not needed by end users. See the
+[Web guide](../docs/developer-guide/web.md) for development and security details.

{symphony_code-0.0.1 → symphony_code-0.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "symphony-code"
-version = "0.0.1"
+version = "0.0.2"
 description = "Symphony coding agent: workspace tools, JSONL sessions, and a Textual TUI on top of symphony-harness (import as coding_agent; run as `symphony`)"
 readme = "README.md"
 license = "MIT"
@@ -31,9 +31,9 @@ Documentation = "https://github.com/Sarthakischauhan/symphony/blob/main/docs/pac
 Source = "https://github.com/Sarthakischauhan/symphony/tree/main/coding_agent"
 
 [project.scripts]
-symphony = "coding_agent.tui.__main__:main"
-symphony-code = "coding_agent.tui.__main__:main"
-coding-agent-tui = "coding_agent.tui.__main__:main"
+symphony = "coding_agent.cli:main"
+symphony-code = "coding_agent.cli:main"
+coding-agent-tui = "coding_agent.cli:main"
 
 [tool.uv.sources.symphony-core]
 workspace = true

{symphony_code-0.0.1 → symphony_code-0.0.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "symphony-code"
-version = "0.0.1"
+version = "0.0.2"
 description = "Symphony coding agent: workspace tools, JSONL sessions, and a Textual TUI on top of symphony-harness (import as coding_agent; run as `symphony`)"
 readme = "README.md"
 license = "MIT"
@@ -31,9 +31,9 @@ Source = "https://github.com/Sarthakischauhan/symphony/tree/main/coding_agent"
 [project.scripts]
 # `symphony` is the primary command; the other two are aliases kept for
 # compatibility and all resolve to the same entry point.
-symphony = "coding_agent.tui.__main__:main"
-symphony-code = "coding_agent.tui.__main__:main"
-coding-agent-tui = "coding_agent.tui.__main__:main"
+symphony = "coding_agent.cli:main"
+symphony-code = "coding_agent.cli:main"
+coding-agent-tui = "coding_agent.cli:main"
 
 [tool.uv.sources]
 symphony-core = { workspace = true }

{symphony_code-0.0.1 → symphony_code-0.0.2}/src/coding_agent/addons/approvals.py

@@ -16,6 +16,7 @@ from pathlib import Path
 from typing import Any, Dict, Optional, Sequence, Union
 
 from core_harness import Addon, EventSink
+from core_harness.models import ToolCall
 
 from coding_agent.config import ApprovalConfig, ensure_spawn_settings
 
@@ -52,6 +53,22 @@ def matching_rule(
     return next((p for p in patterns if any(fnmatchcase(s, p) for s in subjects)), None)
 
 
+def approval_metadata(tool_name: str, arguments: Dict[str, Any], question: str, call_id: str) -> Dict[str, Any]:
+    """What an approval card shows: the subject, the question and the size of the write."""
+    field = RULE_SUBJECTS.get(tool_name)
+    target = str(arguments.get(field) or "").strip() if field else ""
+    written = arguments.get("content") if tool_name == "write_file" else (
+        arguments.get("new_str") if tool_name == "patch" else None
+    )
+    return {
+        "tool_name": tool_name,
+        "tool_call_id": call_id,
+        "target": target,
+        "detail": question,
+        "bytes": len(written.encode("utf-8")) if isinstance(written, str) else None,
+    }
+
+
 class ApprovalPolicy:
     """Path-aware rules. Callers pass the current ``ApprovalConfig``."""
 
@@ -160,7 +177,7 @@ class ApprovalAddon(Addon):
         arguments: Dict[str, Any],
         sink: Optional[EventSink] = None,
         emit: Any = None,
-        tool_call: Any = None,
+        tool_call: Optional[ToolCall] = None,
         **_: Any,
     ) -> Optional[str]:
         approvals = self.approvals
@@ -187,7 +204,9 @@ class ApprovalAddon(Addon):
             choices=APPROVAL_CHOICES,
             default=ALLOW_ONCE,
             kind="approval",
-            metadata={"tool_name": tool_name, "tool_call_id": str(getattr(tool_call, "id", "") or "")},
+            metadata=approval_metadata(tool_name, arguments, prompt, tool_call.id if tool_call is not None else ""),
+            # The harness emit journals the question, so history keeps target, detail and bytes.
+            emit=emit,
         )
         allowed, promote = self.policy.interpret(approvals, answer)
         if promote:
@@ -219,6 +238,7 @@ __all__ = [
     "AUTO_DECISION",
     "ApprovalAddon",
     "ApprovalPolicy",
+    "approval_metadata",
     "DENY",
     "matching_rule",
 ]

{symphony_code-0.0.1 → symphony_code-0.0.2}/src/coding_agent/addons/learning/store.py

@@ -82,7 +82,11 @@ class LearningStore:
         else:
             self.memory_dir = safe_path(self.workspace, ".symphony/memories")
         # Do not resolve away symlinks before validating paths.
-        self.global_root = Path(global_root).absolute() if global_root is not None else safe_path(Path.home(), ".symphony/memories/global")
+        override = os.environ.get("SYMPHONY_HOME", "").strip()
+        # Keep the unresolved path so the ancestor symlink checks below still
+        # protect memory roots, including a configured Symphony home.
+        global_home = Path(override).expanduser().absolute() if override else Path.home() / ".symphony"
+        self.global_root = Path(global_root).absolute() if global_root is not None else safe_path(global_home, "memories/global")
         self.roots = {"workspace": self.memory_dir, "global": self.global_root}
         self.path = safe_path(self.memory_dir, "lessons.jsonl")
         # Markdown fact files. These are the session (and global) record.
@@ -93,8 +97,12 @@ class LearningStore:
         self._lock_depth = 0
         for root in self.roots.values():
             # Validate every ancestor, including a supplied global root.
+            # macOS system directories such as /var may themselves be symlinks;
+            # those are outside the configured home and are not attacker-created
+            # memory roots. Reject the root and every ancestor at or below home.
+            home = Path.home().absolute()
             for parent in (root, *root.parents):
-                if parent.is_symlink():
+                if parent.is_symlink() and (parent == root or parent == home or home in parent.parents):
                     raise ValueError("unsafe memory root")
             for relative in ("topics", "observations/_inbox", "observations/archive", "jobs"):
                 safe_path(root, relative).mkdir(parents=True, exist_ok=True)

{symphony_code-0.0.1 → symphony_code-0.0.2}/src/coding_agent/addons/persistence/active.py

@@ -7,6 +7,7 @@ removes it on a clean exit. A file whose process is gone is stale and ignored.
 
 from __future__ import annotations
 
+import hashlib
 import json
 import os
 from dataclasses import dataclass
@@ -16,7 +17,9 @@ from typing import Any
 
 def active_dir() -> Path:
     """Directory that holds one registry file per live Symphony process."""
-    target = (Path.home() / ".symphony" / "active").expanduser()
+    from coding_agent.config import symphony_dir
+
+    target = symphony_dir() / "active"
     target.mkdir(parents=True, exist_ok=True)
     return target
 
@@ -47,6 +50,32 @@ class ActiveSession:
         }
 
 
+# Advisory lifetime locks coordinate all local hosts, including the TUI. Registry
+# files alone have a check-then-write race. The kernel releases locks on crashes.
+_owned_lock = None
+_owned_session = None
+
+
+def _claim(session_id: str) -> None:
+    global _owned_lock, _owned_session
+    import fcntl
+
+    if _owned_session == session_id:
+        return
+    digest = hashlib.sha256(session_id.encode()).hexdigest()
+    handle = (active_dir() / f"{digest}.lock").open("a")
+    try:
+        fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        if any(item.session_id == session_id and item.pid != os.getpid() for item in list_active()):
+            raise RuntimeError("Session is owned by another live Symphony process")
+    except (OSError, RuntimeError) as exc:
+        handle.close()
+        raise RuntimeError("Session is owned by another live Symphony process") from exc
+    if _owned_lock is not None:
+        _owned_lock.close()
+    _owned_lock, _owned_session = handle, session_id
+
+
 def register_active(
     session_id: str,
     *,
@@ -57,6 +86,8 @@ def register_active(
     pid: int | None = None,
 ) -> ActiveSession:
     """Record that this process owns ``session_id``. Replaces any prior record."""
+    if pid is None or pid == os.getpid():
+        _claim(session_id)
     record = ActiveSession(
         session_id=session_id,
         pid=os.getpid() if pid is None else pid,
@@ -74,6 +105,11 @@ def register_active(
 
 def release_active(pid: int | None = None) -> None:
     """Drop this process's registry file. Missing files are fine."""
+    global _owned_lock, _owned_session
+    if pid is None or pid == os.getpid():
+        if _owned_lock is not None:
+            _owned_lock.close()
+        _owned_lock = _owned_session = None
     path = _path(os.getpid() if pid is None else pid)
     try:
         path.unlink()

{symphony_code-0.0.1 → symphony_code-0.0.2}/src/coding_agent/addons/persistence/jsonl.py

@@ -19,7 +19,7 @@ from contextlib import contextmanager
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Callable, Dict, Iterator, List, Mapping, Optional, Sequence, Union
+from typing import TYPE_CHECKING, Any, Callable, Dict, Iterator, List, Mapping, Optional, Sequence, Union
 
 from coding_agent.addons.persistence.artifacts import (
     append_bytes,
@@ -42,6 +42,10 @@ from coding_agent.addons.persistence.collection import (
 )
 
 _SESSION_ID = re.compile(r"^[A-Za-z0-9._-]+$")
+
+if TYPE_CHECKING:
+    from coding_agent.widget_fields import EventFields
+
 _SKIP_EVENTS = frozenset({"text_delta", "reasoning_delta", "tool_call_delta"})
 _MESSAGE_FIELDS = ("role", "content", "tool_calls", "tool_call_id", "tool_call_metadata")
 _MESSAGE_TYPES = frozenset({"system", "user", "assistant", "tool_result", "message"})
@@ -90,7 +94,9 @@ def sessions_dir(
     first use. Migration is file-by-file and only removes the legacy directory
     after every move has succeeded, so an interrupted migration remains resumable.
     """
-    root = (Path.home() / ".symphony").expanduser().resolve()
+    from coding_agent.config import symphony_dir
+
+    root = symphony_dir()
     if client == "tui":
         target = root / "tui" / "sessions"
         shared = root / "sessions"
@@ -323,6 +329,9 @@ class JsonlPersistence:
         # Product fields (goal, todo, live background jobs) merged into every
         # checkpoint so an interrupted run can be continued later.
         self.checkpoint_metadata: Callable[[], Dict[str, Any]] = dict
+        # Protocol-3 widget fields journaled with each event, so reloads and
+        # session/history keep them. ``build_agent`` sets it.
+        self.fields: EventFields | None = None
 
     def session_dir(self, session_id: str) -> Path:
         """Return a validated session artifact directory (without creating it)."""
@@ -858,6 +867,11 @@ class JsonlPersistence:
     async def append_event(self, *, event_type: str, payload: dict[str, Any]) -> None:
         if event_type in _SKIP_EVENTS:
             return
+        fields = self.fields
+        for name, body in fields.apply(event_type, payload) if fields is not None else [(event_type, payload)]:
+            self._journal(name, body)
+
+    def _journal(self, event_type: str, payload: dict[str, Any]) -> None:
         session_id = str(payload.get("session_id") or "")
         if not session_id:
             return

{symphony_code-0.0.1 → symphony_code-0.0.2}/src/coding_agent/agent.py

@@ -53,6 +53,7 @@ from coding_agent.config.prompts import SYSTEM_PROMPT
 from coding_agent.addons.skills import SkillRegistry, bundled_skills_root
 from coding_agent.addons.manager import UserAddonRuntime, load_user_addons
 from core_harness.extensions import EMPTY_SNAPSHOT
+from coding_agent.widget_fields import EventFields
 from coding_agent.tools import BashJobs, build_tools
 
 
@@ -510,6 +511,7 @@ def build_agent(
         config=loaded,
         overrides=overrides or None,
     )
+    store = JsonlPersistence(sessions_dir(workspace, client=client))
     agent = CodingAgent(
         registry=registry,
         model_id=default_model_id(registry, model_id or resolved.last_model),
@@ -517,7 +519,10 @@ def build_agent(
         sink=sink,
         session_id=session_id,
         config=resolved,
-        persistence=JsonlPersistence(sessions_dir(workspace, client=client)),
+        persistence=store,
     )
-    agent.persistence.client = client
+    store.client = client
+    # Journal the same widget fields the hosts add (protocol 3).
+    store.fields = EventFields()
+    store.fields.bind(agent)
     return agent

symphony_code-0.0.2/src/coding_agent/cli.py

@@ -0,0 +1,49 @@
+"""The ``symphony`` command: route subcommands, else open the TUI.
+
+Each subcommand is imported only when chosen, so ``web``, ``stdio``, ``acp``,
+``bench`` and ``run`` never load Textual or ``coding_agent.tui``.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def main() -> None:
+    command = sys.argv[1] if len(sys.argv) > 1 else None
+    if command in {"--version", "-V"}:
+        from importlib.metadata import PackageNotFoundError, version
+
+        try:
+            value = version("symphony-code")
+        except PackageNotFoundError:
+            value = "unknown"
+        print(f"symphony {value}")
+        return
+    if command == "web":
+        from coding_agent.web.server import main as web_main
+
+        raise SystemExit(web_main(sys.argv[2:]))
+    if command == "stdio":
+        from coding_agent.protocols.stdio.server import main as stdio_main
+
+        raise SystemExit(stdio_main(sys.argv[2:]))
+    if command == "acp":
+        from coding_agent.protocols.acp.server import main as acp_main
+
+        raise SystemExit(acp_main(sys.argv[2:]))
+    if command == "bench":
+        from coding_agent.bench.cli import main as bench_main
+
+        raise SystemExit(bench_main(sys.argv[2:]))
+    if command == "run":
+        from coding_agent.run.cli import main as run_main
+
+        raise SystemExit(run_main(sys.argv[2:]))
+    from coding_agent.tui.__main__ import main as tui_main
+
+    tui_main()
+
+
+if __name__ == "__main__":
+    main()

{symphony_code-0.0.1 → symphony_code-0.0.2}/src/coding_agent/config/__init__.py

@@ -16,6 +16,7 @@ from coding_agent.config.config import (
     SkillsConfig,
     SettingsSource,
     ToolsConfig,
+    UpdatesConfig,
     WebSearchConfig,
     default_coding_agent_harness,
     ensure_spawn_settings,
@@ -41,6 +42,7 @@ __all__ = [
     "SkillsConfig",
     "SettingsSource",
     "ToolsConfig",
+    "UpdatesConfig",
     "WebSearchConfig",
     "default_coding_agent_harness",
     "ensure_spawn_settings",

{symphony_code-0.0.1 → symphony_code-0.0.2}/src/coding_agent/config/config.py

@@ -182,6 +182,17 @@ def default_coding_agent_harness() -> HarnessConfig:
     )
 
 
+class UpdatesConfig(BaseModel):
+    """Pre-start comparison of the installed coding agent with its PyPI release."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = True
+    # False asks before replacing the installed package. True installs the
+    # newer published release without a prompt.
+    auto: bool = False
+
+
 class CodingAgentConfig(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
@@ -194,6 +205,7 @@ class CodingAgentConfig(BaseModel):
     plugins: PluginsConfig = Field(default_factory=PluginsConfig)
     langfuse: LangfuseConfig = Field(default_factory=LangfuseConfig)
     evaluation: EvaluationConfig = Field(default_factory=EvaluationConfig)
+    updates: UpdatesConfig = Field(default_factory=UpdatesConfig)
     last_model: str | None = None
     # Default "direct" inserts that catalog segment. null = stock prompt only.
     personality: str | None = "direct"
@@ -368,6 +380,7 @@ __all__ = [
     "SettingsSource",
     "SkillsConfig",
     "ToolsConfig",
+    "UpdatesConfig",
     "WebSearchConfig",
     "ensure_spawn_settings",
     "load_coding_agent_config",

symphony_code-0.0.2/src/coding_agent/protocols/stdio/README.md

@@ -0,0 +1,109 @@
+# Coding agent host protocols
+
+`stdio.py` is the versioned JSONL boundary for desktop and other external
+hosts. The coding agent owns execution and persisted checkpoints. A host owns
+its composer queue and submits a single prompt per active turn.
+
+The `ready` frame carries `session_id`, `model`, `workspace`, `branch`,
+`client`, `protocol_version` (currently `3`) and `capabilities`. Protocol 2
+advertised `runs`, `resume`, `interrupt`, `input`, `steer`, `models`, `images`,
+`subagents`, and `commands`; protocol 3 adds `sessions`, `model_switch` and
+`widget_fields`. A host sends `run`, `answer`, `interrupt`, or `steer`
+commands, or a request with a `request_id` (below), and reads `event`,
+`input_requested`, `error`, `done`, and reply frames. `answer`, `interrupt`,
+and `steer` are passed to `CoreHarness.submit` as `Answer`, `Interrupt`, and
+`UserInput` operations. `{"type":"steer","prompt":"..."}` adds a user message
+to the active run before its next model call and is an error when no run is
+active.
+
+A question arrives as the ordinary `question_asked` event, the same as in
+every other host, followed by the protocol 2 `input_requested` frame with the
+same `request_id`. Reply to either with one `answer` command.
+Unknown control-plane events can be ignored without losing the terminal
+`done` frame. A later version must change the version number when it changes
+required frame semantics.
+
+After `ready`, send `{"type":"model/list","request_id":"catalog-1"}` on stdin.
+Symphony responds with a `models` frame carrying the same `request_id`. Each
+row has a qualified
+`id` (`provider:model`), display `label`, `provider`, `description`,
+`context_limit` (tokens, or null), and `reasoning_levels`. The default ID is
+also returned as `default`; hosts should keep the qualified ID when selecting
+a model. The provider is the API route, so gateway models identify the gateway
+even when its upstream model has another vendor.
+
+## Requests
+
+Each request carries a `request_id` and gets exactly one reply frame with the
+same `request_id`, or an `error` frame with it.
+
+| Request | Reply | Capability |
+| --- | --- | --- |
+| `{"type":"model/list"}` | `models`: `models` rows and `default` | `models` |
+| `{"type":"command/list"}` | `commands`: the slash-command catalog | `commands` |
+| `{"type":"session/list"}` | `sessions`: this client's parent sessions, newest first, each with `session_id`, `updated_at`, `message_count`, `first_message`, `client`, `active` | `sessions` |
+| `{"type":"session/history","session_id":"..."}` | `session_history`: `session_id`, `messages` (the transcript; assistant `tool_calls` are `{id, type: "function", function: {name, arguments}}` with `arguments` a JSON string), `events` (`[event, payload]` journal pairs) and `children` | `sessions` |
+| `{"type":"model","model":"provider:model"}` | `model_selected`: `model`, `context_limit`; an error during an active run | `model_switch` |
+
+## Subagents
+
+Subagents use the ordinary `event` envelope: the parent emits
+`agent_spawned` with `child_id` and `tool_call_id`; child events carry that
+`child_id` as `agent_id`; the parent emits `agent_completed` or `agent_failed`
+with `child_id` when it settles. Hosts can route child traffic into a nested
+view using the spawning tool call ID.
+
+## Protocol 3: widget fields
+
+`ready` reports `"protocol_version": 3` and the `widget_fields` capability. Every
+protocol 2 key is unchanged; hosts that ignore unknown keys keep working.
+The stdio server and the TUI add these fields through one shared
+`coding_agent.widget_fields.EventFields`. `parent_call_id` is the
+`tool_call_id` of the `spawn_agent` call that started the emitting subagent,
+and `null` for top-level events.
+
+| Event | Added fields |
+| --- | --- |
+| `tool_execution_started` | `call_id`, `parent_call_id` (`started_at` was already present) |
+| `tool_execution_output` | `call_id`, `stream` (`"stdout"` or `"stderr"`), `parent_call_id` (from the call's `tool_execution_started`) |
+| `tool_execution_completed` | `call_id`, `exit_code`, `summary`, `search_results`, `parent_call_id` (`status`, `result` and `duration_ms` were already present) |
+| `question_asked` (approval) | `target`, `detail`, `bytes` (`tool_call_id`, `choices`, `default` were already present) |
+| `question_asked` (`ask_user`) | `tool_call_id`: the asking call |
+| `input_requested` (approval) | top-level `target`, `detail`, `bytes` (also kept in `metadata`) |
+| `agent_spawned` | `parent_call_id` (same value as `tool_call_id`) |
+| `subagent_step` (new, derived) | `session_id` (the parent session), `agent_id`, `parent_id`, `parent_call_id`, `turn`, `started_at`; follows each subagent `turn_started` |
+
+- `exit_code` is the bash process's exit status; it is `null` for other tools,
+  background jobs, and timeouts. A non-zero exit is `status: "error"` and the
+  result starts with `exit=N`, but consumers should read `exit_code`.
+- `summary` is `{lines, matches, added, removed, start_line}`, each an
+  integer or `null`: `lines` for bash and read_file, `matches` for search,
+  `lines` and `added` for write_file, `added`, `removed` and `start_line` for
+  patch, and `start_line` for read_file too. Failed non-bash calls report all
+  `null`.
+- `start_line` is recorded per call by the tool, never parsed from `result`.
+  For patch it is the 1-based line, in the file as it was before the edit,
+  where `old_str` first matched. For read_file it is the number of the first
+  line of a text read (its `offset`); each result line is that number plus its
+  index, right-aligned to one width, then `|`. It is `null` for image reads
+  and reads that returned no lines.
+- `search_results` (search only, else `null`) lists the search tool's results
+  in order: `{path, line, text}`, where `line` is `null` and `text` is empty
+  in files mode. `summary.matches` is its length.
+- Answer a question or an approval with the `answer` command:
+  `{"type":"answer","request_id":"...","value":"<one of choices>"}`.
+- `bytes` is the UTF-8 size of a write_file `content` or patch `new_str`, else `null`.
+- The session journal stores the same fields: `build_agent` gives the
+  JSONL store its own `EventFields`, approval questions are emitted through
+  the harness so they are journaled, and `subagent_step` is journaled in the
+  parent session. `session/history` events and resumed sessions therefore
+  carry `call_id`, `parent_call_id`, `duration_ms`, `exit_code`, `summary`,
+  `search_results`,
+  the approval `target`/`detail`/`bytes`, and `subagent_step`.
+- `tool_execution_output` chunks are live only. Bash emits them on the sink,
+  outside `CoreHarness.emit`, so they are not stamped or journaled; the
+  completed event's `result` is the stored output. Journaling `stream` per
+  chunk needs a core change: route chunks through `CoreHarness.emit` (or hand
+  tools a stamped emit).
+- Sessions recorded before protocol 3 lack these fields. Clients render those
+  calls without the facts; they do not derive them from `result` text.