How it works
Context propagation carries a small, structured execution envelope alongside work as it crosses a boundary. The boundary might be a process, queue, tool server, subagent, or remote service. The envelope identifies where the work came from and which run, step, or delegated action it belongs to.
A typical propagation path is:
- The harness creates canonical identifiers and records the originating request.
- Before dispatch, it injects approved metadata into the call, message, or job envelope.
- The receiver extracts and validates that metadata rather than trusting it blindly.
- The receiver creates its own child execution record, linked to the parent.
- Any further dispatch repeats the process without widening permissions or copying unnecessary data.
Useful propagated fields can include a run ID, parent step ID, trace identifier, actor or delegation reference, permission scope, deadline, attempt number, and idempotency key. These fields do different jobs. Correlation fields establish causality. Control fields constrain execution. Recovery fields help the harness decide whether to retry, resume, or compensate.
Propagation should be explicit and selective. Copying an entire prompt, credential set, or mutable session object across every boundary creates leakage and ambiguity. The receiver needs enough context to interpret and govern the work, not an unrestricted clone of the caller’s environment.
Why it matters in an agent harness
An agent run rarely stays inside one synchronous call. A planner delegates to a worker. The worker invokes a tool. The tool emits an event. A retry may continue on another process. Without propagated context, those operations still happen, but the harness loses the causal chain that explains why they happened.
That loss weakens observability first. Logs from separate components cannot be reliably joined, and a tool failure appears detached from the decision that produced it. It also weakens evaluation. If an evaluator can see the final answer but cannot associate it with retrieval steps, approvals, retries, or tool effects, it cannot distinguish a model error from an orchestration error.
Control depends on propagation too. A downstream worker needs to know which execution limit, deadline, permission scope, or approval decision applies to its action. However, carrying an authority reference is not the same as granting authority. Each boundary should validate the reference and derive the permissions appropriate to that receiver. Blind inheritance can turn propagation into a confused-deputy path, where a component exercises privileges the originating request did not justify.
Recovery becomes more reliable when attempts and side effects remain attached to their origin. An idempotency key can help a receiver recognize repeated delivery. A parent step ID can show whether a timed-out call later completed. A checkpoint reference can tell the harness where resumption is valid. These mechanisms do not make execution deterministic, but they make uncertain outcomes legible enough to handle deliberately.
The practical boundary is data minimization. Propagate identifiers and enforceable control metadata by default. Pass task content only where the task requires it. Keep secrets in scoped credential systems rather than treating the context envelope as a convenient transport.
Context propagation vs context assembly
The distinction changes where you put policy. Context propagation moves execution metadata between components. Context assembly selects the information presented to a model or worker so it can perform a task.
| Axis | Context propagation | Context assembly |
|---|---|---|
| Primary purpose | Preserve causality and control across boundaries | Build the task-specific working context |
| Typical contents | Run IDs, parent links, deadlines, scopes, attempts | Instructions, retrieved evidence, memory, tool descriptions |
| Main risk | Broken attribution or unintended authority inheritance | Irrelevant, stale, conflicting, or oversized input |
| Policy question | What must survive this boundary? | What does this worker need to reason correctly? |
The two mechanisms meet at dispatch. Propagated metadata tells the receiver how the work is governed; assembled context tells it what work to do. Keeping them separate makes it easier to redact task data, rotate storage formats, or change model inputs without breaking execution identity.
The Rifty take
We treat context propagation as a control protocol, not a logging convenience. We optimize for a small, typed envelope with explicit ownership at every boundary, and we accept the implementation cost of validation because invisible authority inheritance is a worse tradeoff. Task content may be reconstructed; causal identity and control metadata must remain intact.
Implementation checks
- Define one canonical format for run, parent, attempt, and delegation identifiers.
- Document which component creates each field and which components may modify it.
- Inject and extract context at every queue, process, tool, and subagent boundary.
- Reject malformed or contradictory control metadata instead of silently replacing it with plausible defaults.
- Validate permission and approval references at the receiving boundary; never treat possession as authorization.
- Create child execution records rather than reusing one identity for an entire fan-out.
- Propagate deadlines and cancellation state in forms the receiver can enforce.
- Use idempotency keys where messages or tool requests may be delivered more than once.
- Keep credentials, full prompts, retrieved documents, and mutable memory out of the envelope unless explicitly required.
- Test partial failure: delayed replies, duplicate delivery, missing parents, expired approvals, and retries on another worker.
- Verify that an operator can trace a side effect back to the originating request and the exact delegated step.
- Record any deterministic reconstruction or fallback visibly in the execution trace.
Frequently asked questions
What information should an agent harness propagate?
Propagate the minimum metadata needed for causality, control, and recovery: run and parent identifiers, attempt number, deadline, permission or delegation references, approval state references, and idempotency keys. Task data should travel separately and only when the receiving component requires it. Credentials should remain scoped and independently resolved.
Should permission scopes be inherited through propagated context?
No. A propagated scope should be treated as a claim or reference that the receiving boundary must validate. The receiver should derive an effective scope for its own operation, usually equal to or narrower than the caller’s authority. Blind inheritance can grant a downstream component permissions its task does not require.
How is context propagation different from distributed tracing?
Distributed tracing is one consumer of propagated context, focused on correlating spans and measuring execution. Harness context can also carry enforceable control and recovery metadata such as deadlines, attempts, delegation references, and idempotency keys. Trace identifiers explain where an operation belongs, but they should not themselves authorize the operation.
What happens when propagated context is missing or invalid?
The boundary should fail according to the field’s role. Missing optional correlation data may produce a visible orphan record, while missing permission, approval, or recovery metadata should block the affected operation. Silently generating replacement values can split one run into false histories or allow work to proceed without its required controls.
How should context propagation work across retries?
A retry should retain the originating run and parent relationship while receiving a distinct attempt identity. Reuse the relevant idempotency key when the intended side effect is the same. This lets the harness distinguish repeated delivery from new work, associate late responses correctly, and avoid presenting multiple attempts as unrelated operations.