Emit overlap-aware activity events for parallel agent runs

[dgenio]

Context

Parallel Claude Code-style agents working on the same repository introduce a coordination failure mode that is not captured by single tool-call authorization alone: multiple agents can touch the same files, repeat work, rely on stale assumptions, or produce evidence that reviewers cannot correlate.

agent-kernel already owns capability grants, policy decisions, execution, bounded frames, and audit traces. That makes it a good source of structured activity events that downstream dashboards or control planes can use to detect overlap.

Related context: #240 explores dashboard-friendly activity events. This issue focuses specifically on parallel-agent overlap semantics.

Problem

When several agents run concurrently, operators need answers such as:

• which agent/session claimed or touched this path?
• which files are being edited by more than one run?
• which run produced the evidence a reviewer should inspect?
• which policy decisions occurred during each run?
• did a later run rely on stale assumptions from an earlier run?

Audit traces remain essential, but they are not always shaped for live coordination.

Proposal

Extend the activity-event design with explicit overlap-aware event types for multi-agent runs.

Possible event types:

agent_run_started
agent_run_completed
agent_claimed_path
agent_touched_path
agent_overlap_detected
agent_policy_gate
agent_evidence_written
agent_review_ready
agent_stale_assumption_detected

Each event should carry safe metadata only:

• run/session id,
• agent id/type if available,
• principal id/hash,
• capability id,
• path or path hash,
• action id,
• decision/status,
• timestamp/duration,
• evidence artifact reference/handle,
• redaction/sensitivity marker.

Raw tool arguments/results should remain behind existing firewall/audit rules.

Non-goals

• Do not build a dashboard in agent-kernel.
• Do not implement git locking or worktree management in the kernel.
• Do not expose raw tool payloads or sensitive data in coordination events.
• Do not replace the authoritative audit trail; these events are operational signals.

Acceptance criteria

• Add or extend a design note covering parallel-agent activity events.
• Define a minimal schema for overlap-aware events.
• Add a fixture/example JSONL stream with at least two runs touching overlapping paths.
• Add tests showing sensitive arguments/results are excluded or redacted.
• Document how a control plane or dashboard could consume these events without depending on a specific agent UI.
• Decide whether the feature is experimental API, callback hook, or example-only export.

Why this matters

As coding agents move from one assistant to multiple concurrent workers, authorization and audit are necessary but not sufficient. Teams also need a coordination surface: what is active, what overlaps, what evidence exists, and what a reviewer should inspect before trusting the run.