Class ToolContext

src/tool_system/context.py:67–376

@dataclass
class ToolContext:
    workspace_root: Path
    permission_context: ToolPermissionContext = field(
        default_factory=lambda: ToolPermissionContext(mode="bypassPermissions")
    )
    cwd: Path | None = None
    read_file_fingerprints: dict[Path, tuple[int, int] | tuple[int, int, bool]] = field(default_factory=dict)
    task_manager: TaskManager = field(default_factory=TaskManager)
    mcp_clients: dict[str, Any] = field(default_factory=dict)
    lsp_client: Any | None = None
    todos: list[dict[str, Any]] = field(default_factory=list)
    tasks: dict[str, dict[str, Any]] = field(default_factory=dict)
    # Chapter-10 / Chunk B / WI-1.3 — typed runtime-task registry. Houses
    # ``LocalShellTaskState`` / ``LocalAgentTaskState`` / etc. as
    # ``TaskStateBase`` subclasses. Replaces the un-typed
    # ``background_bash_tasks`` and ``_internal=True`` agent entries that
    # used to live on ``tasks``. ``runtime_tasks`` is the source of truth
    # for the chapter-10 task state machine; ``tasks`` continues to host
    # ``tasks_v2``/todo entries for the unrelated TaskCreate system.
    runtime_tasks: RuntimeTaskRegistry = field(default_factory=RuntimeTaskRegistry)
    # WI-5.1: per-message tool-result aggregate counter. The execution
    # pipeline (Step 11) reads + increments this each time a tool result
    # is mapped to its API form; when the running total exceeds
    # ``MAX_TOOL_RESULTS_PER_MESSAGE_CHARS`` (default 200K) the next
    # result is persisted to disk regardless of its individual size.
    # Reset to 0 between messages by the turn-loop dispatcher.
    #
    # ``_aggregate_lock`` synchronizes the read-decide-write across
    # concurrent tool dispatches (critic B6). The query loop's concurrent dispatch
    # uses ``asyncio.to_thread`` to fan out concurrency-safe tools (Read,
    # Grep, Glob) — without this lock, N threads would all read 0, all
    # decide their block is under the cap, and the per-message budget
    # would be silently bypassed. The full read+decide+write runs
    # serialized so the persistence decision uses the LIVE counter and
    # the cap is strictly enforced. Cost: the rare persist-to-disk path
    # serializes against the lock, but persists are O(1) per turn in
    # typical workloads (the common case under-threshold returns the
    # block without I/O).
    tool_result_chars_so_far: int = 0
    _aggregate_lock: threading.Lock = field(default_factory=threading.Lock)
    # Session-cumulative tokens spent on client-side advisor calls.
    # ``src/tool_system/tools/advisor.py`` accumulates here on every
    # consultation; the status surface reads them to display
    # ``advisor: <in>/<out>`` next to the worker's
    # token counts. Distinct from ``tool_result_chars_so_far`` (which
    # is a per-message budget tied to API-result persistence) — these
    # are per-session totals for UI display.
    advisor_input_tokens: int = 0
    advisor_output_tokens: int = 0
    # Chapter-10 / Chunk F / WI-6.1 — agent-name registry. Maps the
    # human-readable ``name`` (passed via Agent({name: "researcher"}))
    # to the random ``agent_id`` returned by the spawn. SendMessage
    # consults this registry first when resolving a ``to:`` field;
    # falling back to "treat ``to`` as a raw agent_id" when the name
    # isn't registered preserves the legacy code path.
    #
    # Per Chunk-F-Phase-6 critic concern C1 (Phase-7 fix): the registry
    # is a typed ``AgentNameRegistry`` (not a bare dict) so the