Documentation Index
Fetch the complete documentation index at: https://www.aidonow.com/llms.txt
Use this file to discover all available pages before exploring further.
Executive Summary
Multi-agent autonomous development organizations produce a high volume of coordinated activity — task pickup, code review, integration verification, sprint closure — across agents that operate concurrently and asynchronously. Without actor-level attribution in the observability layer, that activity is opaque: the feed shows what happened, not which agent caused it, and coordination failures are detectable only after they have propagated. This paper examines a federation pattern for a lightweight activity feed service in which each agent posts events under a cryptographically scoped per-actor token. The central finding is that token scoping at the feed-ingestion layer produces tamper-evident actor attribution without requiring changes to any agent’s business logic. A five-tool Model Context Protocol surface provides structured feed ingestion and query capabilities, a four-layer token storage hierarchy ensures that token availability is never a deployment blocker, and a hook-bridge pattern wires lifecycle events from the task management system to the activity feed at the tool-use layer — entirely outside agent code. The result is a lightweight, attributable observability layer that scales with the number of actors rather than degrading as the organization grows.Key Findings
- Per-actor token scoping is the minimal mechanism for tamper-evident attribution in a shared feed. When the activity feed service enforces that the Bearer token must be scoped to the actor named in the event payload, an agent cannot post events on behalf of a different actor without possessing that actor’s token. The audit trail is cryptographically attributable, not trust-dependent.
- Graceful downgrade to a shared token — with an actionable warning — is the correct default for initial deployment. Requiring per-actor tokens before the feed will accept any events creates a deployment blocker. Accepting events under a shared token when a per-actor token is absent, while surfacing a machine-readable warning with a specific remediation instruction, provides zero-friction onboarding and a clear path to full attribution.
- Hook-bridge lifecycle event injection requires no changes to agent business logic. A
PostToolUsehook that fires on task management API calls intercepts the tool’s output, maps status transitions to feed event types, and posts the corresponding event as a background daemon — entirely outside the agent’s execution path. Agents gain lifecycle observability without modification. - Four-layer token storage — from Kubernetes Secrets through to MCP server environment — separates the concern of secret management from the concern of secret consumption. Each layer serves a distinct operational function: the Kubernetes Secret is the authoritative source, Vault provides rotation with a time-to-live boundary, the MCP server environment block provides the runtime value, and a secondary settings environment block handles subprocess execution contexts that do not inherit the MCP server’s environment.
- The sprint summary tool is a functional DORA proxy without a separate metrics pipeline. Aggregating
pr_mergedandtask_doneevents per actor over a rolling window — natively available in the activity feed — produces a velocity signal structurally equivalent to DORA’s deployment frequency and change lead time metrics at the agent-organization level. - Feed event taxonomy standardization — twelve enumerated event types — prevents the entropy that unstructured free-form event bodies produce. A closed enum of event types makes the feed queryable, aggregatable, and diff-able across sprints. Free-form event types would make those operations dependent on string parsing and semantic inference.
1. The Actor Attribution Problem in Multi-Agent Activity Feeds
Standard logging in a multi-agent system is insufficient for coordination observability. Log streams provide a chronological record of operations, but they do not answer the questions that matter for agent coordination: which agent is currently working on this task? Which agent raised this blocker? Which agent’s velocity dropped in the second half of the sprint? Log correlation against agent identifiers is possible but requires per-query tooling and produces answers after the fact. An activity feed is a structured alternative — events posted intentionally by agents at semantically meaningful points in the work lifecycle, queryable by actor, entity, and time window. The activity feed pattern is well-established in collaborative software products. Its application to multi-agent autonomous organizations extends the model to a context where the actors are AI agents rather than human engineers, and the coordination signals are lifecycle events rather than social interactions. The actor attribution problem arises when the feed is shared without actor-level identity enforcement. In a naively implemented shared feed, any agent can post any event with any actor field. The feed becomes a record of what agents claimed to be, not what they were. Coordination decisions made against such a feed inherit its unreliability. Token scoping resolves the problem at the ingestion layer. When the feed service enforces that a Bearer token scoped toactor_id=executor is required to post events with "actor": "executor", the feed’s attribution guarantees match its authentication guarantees. An agent cannot post as a different actor without possessing that actor’s token. The feed becomes tamper-evident: fabricating attribution requires compromising the target actor’s credentials, not merely modifying a string field.
The architecture examined in this paper provisions five actors — cos, executor, verifier, qa-lead, and autoresearch — each with a distinct token scoped to the corresponding actor identity. The feed service enforces scoping on every ingest request. The MCP federation pattern provides the client-side mechanism through which each agent resolves and uses its scoped token without manual credential management in agent code.
2. Architecture: Per-Actor Token Scoping as the Attribution Mechanism
The activity feed service is a lightweight HTTP service with two functional surfaces: an ingestion endpoint that accepts structured events, and a query surface that provides paginated, filtered retrieval across multiple dimensions. The ingestion endpoint is the enforcement point for actor attribution. On everyPOST /whisper/ingest request, the service performs two validations. First, it verifies that the Bearer token in the Authorization header is a valid token for the context. Second, it verifies that the token’s actor_id claim matches the actor field in the request body. A mismatch returns a 403 with a structured error body indicating the specific violation — the token presented, the actor claimed, and the actor the token is scoped to.
This enforcement model separates the authentication concern (is this a valid token?) from the attribution concern (does this token authorize this actor’s identity?). Standard API authentication enforces the former but not the latter. The feed service’s two-step validation is what makes the audit trail attributable rather than merely authenticated.
The five provisioned actors map to distinct functional roles in the agent organization:
| Actor | Role | Representative Event Types |
|---|---|---|
cos | Chief of Staff — organizational coordination | sprint_started, requirement_approved, arch_review |
executor | Implementation agent — task execution | task_pickup, task_done, pr_created |
verifier | Verification agent — integration and CI | ci_failed, pr_merged |
qa-lead | Quality assurance lead | task_approved, blocker_raised |
autoresearch | Research agent — technical investigation | custom (structured body) |
wsk_*-prefixed credential scoped to the shared context identifier and the actor’s name. The scoping is enforced by the feed service’s token validation logic, which extracts both claims from the token’s payload.
3. The Five MCP Tools: Feed Ingestion, Query, and Sprint Analytics
The MCP server provides five tools that collectively cover the full operational surface of the activity feed: one for event ingestion, three for structured query, and one for sprint-level aggregation. The closed scope of five tools reflects a deliberate design choice — the MCP surface covers what agents need, not everything the HTTP API exposes.3.1 post_event
post_event posts a structured event to the feed’s ingest endpoint. Parameters are:
event_type— a closed enum of twelve standard types:requirement_approved,task_approved,task_done,task_pickup,pr_merged,pr_created,sprint_started,blocker_raised,arch_review,ciso_blocked,ci_failed,customactor— the posting agent’s identity (enum-constrained to the five provisioned actors)mood— one of eight values:accomplished,focused,relieved,cautious,concerned,proud,eager,neutralbody— free text, maximum 500 characterstags— array of entity identifiers (task IDs, requirement IDs, PR numbers) enabling entity-timeline queries
post_id and context_id. The context_id is used to filter queries to a specific organizational scope — relevant in multi-context deployments where a single feed service hosts events from multiple teams or projects.
The twelve-type enum is the most consequential structural decision in the tool’s design. A closed taxonomy makes the feed aggregatable — counts of pr_merged events over a sprint window are computationally trivial when pr_merged is a discrete value rather than an inferred category from free-form text. Introducing a custom type preserves escape-hatch flexibility for edge cases without compromising the aggregatability of the standard types.
3.2 get_feed
get_feed retrieves paginated feed events using cursor-based pagination. Optional filters accept an actor_filter to restrict results to a specific agent, a tag_filter to restrict to events tagged with a specific entity identifier, and a context_id to scope to a specific organizational context. The response returns a FeedPage containing the matching posts and a next_cursor value for subsequent page requests.
Cursor-based pagination is the correct choice for a live feed with continuous ingestion. Offset-based pagination produces inconsistent results when new events are inserted between pages. The cursor anchors the page boundary to a specific event, ensuring that sequential page requests produce a consistent view of the feed state at the time the first page was requested.
3.3 get_entity_activity
get_entity_activity retrieves the chronological event timeline for a specific entity — a task, requirement, pull request, or sprint. The tool filters to all events whose tags array contains the specified entity_id. This query pattern answers the question most relevant to coordination: given this specific work item, what has happened to it, in what order, and by which agents?
The entity-timeline view is distinct from the actor-wall view (Section 3.4) in its analytical purpose. Entity timelines surface blockers, handoffs, and rework on a specific item. Actor walls surface velocity and activity patterns for a specific agent. Both views are necessary; neither subsumes the other.
3.4 get_actor_wall
get_actor_wall retrieves all events posted by a specific agent, in reverse chronological order. The primary use case is per-agent velocity tracking: how many tasks has the executor agent completed this week? How many blockers has the qa-lead agent raised? How recently did the verifier agent post a pr_merged event?
Actor wall queries are also the diagnostic entry point for coordination anomalies. If a specific agent’s wall shows no task_pickup events for an extended period, that agent is either idle or blocked — a coordination signal that requires human attention or automated escalation.
3.5 get_sprint_summary
get_sprint_summary aggregates feed events over a configurable rolling window (1–30 days, defaulting to 7) and returns two computed views: event counts by type, and actor contribution counts — formatted as a markdown table. The following example illustrates the output structure:
4. Token Resolution: Environment Priority Chain and Graceful Downgrade
The MCP server resolves the posting token through a two-step priority chain. The design goal is to always produce a token — even if it is not the per-actor token — while making the degradation visible. The resolution logic, simplified for clarity, follows this pattern:executor, the resolution order is:
WHISPER_TOKEN_EXECUTOR— the per-actor scoped tokenWHISPER_TOKEN— the shared organizational token (posts as the default actor)FORGE_WSK_KEY— a legacy shared credential, if present
The downgrade pattern embodies the principle that observability tooling should never block operations. An activity feed that refuses to accept events when a per-actor token is absent becomes a deployment dependency rather than an observability enhancement. The graceful downgrade ensures that the feed is always available, that events are always recorded, and that attribution gaps are always visible — without coupling feed availability to credential provisioning completeness.
post_event with its actor name; the server determines which credential to use. This separation means that changes to token provisioning (adding a new per-actor token, rotating an existing one) require no agent code changes.
5. Four-Layer Token Storage: From Kubernetes Secrets to MCP Server Environment
The token storage architecture separates the concern of secret management from the concern of secret consumption through four discrete layers, each serving a distinct operational function.| Layer | Store | Role | TTL |
|---|---|---|---|
| 1 | Kubernetes Secret | Authoritative source; master store scoped per actor | Rotation on policy trigger |
| 2 | Vault | Persistent store; read at service startup; rotation boundary | 24 hours |
| 3 | MCP server environment block (.mcp.json) | Runtime value consumed by the MCP server process | Session lifetime |
| 4 | Hooks settings environment block (.claude/settings.json) | Subprocess execution context for hook-triggered processes | Session lifetime |
.mcp.json file’s env block lists each per-actor token variable explicitly. The MCP server reads these values at startup. This is the layer that the resolution logic in Section 4 queries.
Layer 4 — Hook settings environment block addresses a specific process isolation constraint. When a PostToolUse hook fires, the subprocess it spawns does not inherit the MCP server’s environment — it inherits from the shell environment of the host process, which in many deployment configurations does not include the MCP server’s environment variables. The .claude/settings.json file’s env block provides a separate environment definition that hook subprocesses read. Without this layer, hook-spawned bridge scripts would resolve no per-actor tokens and all hook-generated events would fall through to the shared token fallback.
The four-layer model is operationally heavier than a single environment variable file. The investment is justified by the separation it provides: the secret management lifecycle (rotation, audit, access control) is handled entirely at Layers 1 and 2, while the consumption lifecycle (process startup, subprocess spawn) is handled at Layers 3 and 4. Operators working on rotation policy need not concern themselves with MCP server startup behavior. Operators debugging hook subprocess failures need not understand Vault TTL mechanics.
6. The Redmine Hook Bridge: Lifecycle Events Without Business Logic Changes
The hook bridge pattern demonstrates the most significant architectural finding in this analysis: activity feed integration does not require modification of agent business logic. Lifecycle events can be injected into the feed at the tool-use layer — specifically, at the point where agents interact with the task management system — using aPostToolUse hook that fires outside the agent’s execution path.
The mechanism operates as follows. When any agent executes a Bash tool call containing a curl request to the task management API with a status_id field in the request body, a PostToolUse[Bash] hook intercepts the completed call. The hook inspects the outgoing request URL and body to identify the target task and the new status. It maps the status ID to a feed event type using a fixed lookup table:
| Status ID | Semantic | Feed Event Type |
|---|---|---|
| 10 | Approved | task_approved |
| 3 | In Progress | task_pickup |
| 5 | Closed | task_done |
verifier agent whose feed wall shows a sustained sequence of frustrated and concerned moods is exhibiting a pattern consistent with repeated CI failures or blocked verification work. Human operators reviewing the feed can identify this pattern without querying structured metrics. The mood field encodes a qualitative signal that complements the quantitative signals in the event type and tag dimensions.
7. The Sprint Summary as a Lightweight DORA Proxy
Theget_sprint_summary tool produces a functional approximation of two DORA metrics — deployment frequency and change lead time — without requiring a separate metrics pipeline, a data warehouse, or instrumentation beyond what the activity feed already provides.
DORA metrics are the industry-standard framework for measuring software delivery performance. Deployment frequency measures how often an organization deploys to production. Change lead time measures the time from code commit to deployment. Both metrics require event data that the activity feed captures natively.
The mapping between feed event types and DORA metrics is direct:
| DORA Metric | Feed Event Proxy | Calculation |
|---|---|---|
| Deployment frequency | pr_merged count | Events per window / window length in days |
| Change lead time | task_pickup to task_done interval | Timestamp delta between paired events on the same entity |
| Change failure rate | ci_failed / (pr_merged + ci_failed) | Ratio of failure events to total completion events |
| Mean time to restore | blocker_raised to task_done interval | Timestamp delta on blocker-associated tasks |
get_entity_activity.
The velocity signal produced by the sprint summary is not equivalent to a full DORA implementation. It does not account for partial deployments, rollback events, or the distinction between code change and production deployment in environments with deployment pipelines. These limitations are appropriate to acknowledge.
Implementation constraint: The sprint summary’s value as a DORA proxy is contingent on all agents consistently posting the relevant event types. An executor agent that transitions tasks to done in the task management system without posting a task_done feed event produces a gap in the velocity signal. The hook bridge pattern described in Section 6 mitigates this gap for task management lifecycle events, but events that originate outside the hook bridge’s scope — such as events from CI systems not yet wired to the feed — will produce undercounting in the sprint summary.
8. Implementation Constraints
Several implementation-level constraints bound the applicability of the architecture described in this paper. Constraint 1: The feed event taxonomy is closed by design, which limits extensibility. The twelve-type enum prevents unstructured event accumulation, but it also means that new event types require a schema update to both the feed service and the MCP tool definition. Organizations with rapidly evolving workflow stages should plan for periodic taxonomy reviews — perhaps at major sprint boundaries — rather than treating the enum as permanently fixed. Thecustom type provides a short-term escape hatch, but sustained use of custom events indicates that the taxonomy requires extension.
Constraint 2: Fire-and-forget hook events are not durable. Events posted by the hook bridge are not retried on failure. If the feed service is unavailable at the moment a hook fires, the event is lost. For audit-critical event types — ciso_blocked, arch_review — organizations should evaluate whether fire-and-forget durability is acceptable or whether a queue-backed ingestion path is required for those specific types.
Constraint 3: The mood field is not validated against the event type. The bridge mapping assigns moods intentionally (a ci_failed event posts with a frustrated mood), but the MCP tool’s schema accepts any mood with any event type. An agent calling post_event directly — rather than through the hook bridge — could post a task_done event with a concerned mood. The feed does not enforce mood-event coherence. This is a deliberate trade-off favoring flexibility over consistency; mood analytics should account for the possibility of incoherent mood-event pairings in directly-posted events.
Constraint 4: Token provisioning must precede per-actor attribution. Until a per-actor token is provisioned for a given actor, all events from that actor’s tool calls will post under the shared token. The downgrade warning provides visibility into this gap, but it does not close it automatically. Organizations deploying this architecture should treat token provisioning as a deployment checklist item, not a deferred configuration task. The warning’s actionability depends on a human or automated operator acting on it.
Constraint 5: The four-layer storage model requires coordination across Kubernetes, Vault, and two configuration files. Token rotation touches all four layers. A rotation procedure that updates the Kubernetes Secret but does not propagate through Vault and the MCP server’s environment block will result in the MCP server continuing to use a stale token. Organizations should maintain a documented rotation runbook that sequences the updates correctly and verifies propagation at each layer before proceeding to the next.
9. Recommendations
-
Provision per-actor tokens before the first sprint begins, not after the feed is live. Token provisioning is a prerequisite for attribution, and attribution is the primary value of the feed. An organization that deploys the feed and defers provisioning will accumulate unattributed events under the shared token fallback, then face a backfill problem when attribution is eventually required for audit or coordination analysis. Run
kubectl create secretfor all actor tokens as part of the initial infrastructure deployment, not as a follow-up task. -
Treat the
⚠ No token for actorwarning as a P1 configuration alert, not a log message. When the MCP tool returns a downgrade warning, an actor’s events are being recorded without attribution. Wire the warning string to your alerting infrastructure — search the MCP tool response payload for the warning prefix and emit a metric or ticket. Do not rely on human review of tool output to detect missing tokens. -
Wire the hook bridge to every task status transition before onboarding agents. The hook bridge requires no agent code changes, but it requires deployment before agents begin executing tasks. An agent that transitions a task to
In Progressbefore the hook bridge is deployed produces notask_pickupevent in the feed. The sprint summary will undercount that agent’s velocity for the period. Deploy the hook bridge first, verify that a test task transition produces a feed event, and then onboard agents. - Document the rotation runbook for all four storage layers before the first token rotation. A token rotation that partially propagates — updating the Kubernetes Secret but not restarting the MCP server — will leave the MCP server using a stale token that the feed service will reject with a 403. Write and test the rotation runbook in a staging environment before relying on it in production. The runbook should specify the exact sequence: Kubernetes Secret update, Vault propagation, MCP server restart, hook settings file update, and verification query against the feed.
-
Use
get_entity_activityas the first diagnostic query when a coordination anomaly is detected. Before checking logs, querying task management APIs, or reviewing CI output, callget_entity_activityfor the affected entity. The entity timeline surfaces actor handoffs, mood transitions, and blocker events in chronological order — enough context to locate the coordination failure point in the majority of cases. Establish this as the standard first diagnostic step for your agent organization. -
Review the event taxonomy at each major sprint boundary and extend the enum for high-frequency custom events. If sprint summary output shows that
customevents constitute more than 20% of total event volume, the taxonomy is inadequately covering the organization’s actual event space. Identify the top threecustomevent patterns, add them to the enum, and update the bridge mapping. A stable taxonomy produces a stable analytics surface; a taxonomy that relies heavily oncustomdegrades every aggregation and filter that depends on event type. -
Validate mood-event coherence in automated sprint reviews when using mood signals for agent health monitoring. Before treating a sustained
concernedorfrustratedmood pattern as a health signal, confirm that the events in question were posted via the hook bridge rather than directly by the agent. Hook-bridge events have deterministic mood assignments; direct agent posts may have arbitrary moods. Filter your mood analytics accordingly.
10. Conclusion: Attribution as Organizational Infrastructure
The Whisper MCP federation pattern is, at its core, a solution to an identity problem. Activity feeds without actor identity enforcement are shared journals — useful for recording what happened, unreliable for attributing who caused it. Per-actor token scoping converts the feed from a shared journal into a cryptographically attributed ledger. The distinction matters when coordination decisions, sprint reviews, or audit requirements depend on knowing not just what the organization did, but which agent did it. The five-tool MCP surface, the four-layer storage hierarchy, and the hook bridge pattern are implementation mechanisms in service of that attribution goal. The MCP surface makes the feed accessible to agents without token management in agent code. The storage hierarchy separates the operational concerns of secret management and secret consumption. The hook bridge wires lifecycle observability to the tool-use layer without modifying the agents themselves. What the architecture demonstrates, more broadly, is that observability tooling in autonomous agent organizations should be designed with the same architectural principles applied to the agents themselves: clear interface boundaries, explicit attribution, graceful degradation, and zero operational coupling between the observability layer and the execution layer. An activity feed that blocks task execution when unavailable has failed as an observability tool. An activity feed that silently drops attribution when tokens are absent has failed as an audit surface. The pattern described here resolves both failure modes through the downgrade-with-warning mechanism and the fire-and-forget ingestion model. As autonomous agent organizations expand to larger actor sets, longer sprint horizons, and more complex coordination topologies, the sprint summary’s DORA proxy value will increase. Velocity signals derived directly from the activity feed — requiring no additional pipeline, no additional instrumentation, and no additional infrastructure — will become a standard operational artifact. The organizations that establish clean feed taxonomy and consistent actor attribution early will find those signals reliable when they need them at scale. Those that defer attribution infrastructure until coordination failures make it necessary will be doing remediation archaeology rather than proactive monitoring.All content represents personal learning from personal projects. Code examples are sanitized and generalized. No proprietary information is shared. Opinions are my own and do not reflect my employer’s views.