Foundations, lesson 11

Passing context

A subagent knows only what its prompt holds

A coordinator collects findings from researchers, then starts a writer subagent to draft the recall report. The writer is handed the task and nothing else. It cannot name a source for any claim, and nobody can check a figure. This is the agent at Lumen Supply, an online electronics shop. You will watch the writer work with no findings, then fix the handoff so every claim keeps its source and date.

I doWatch the failure and its fix.

The brief is the writer's whole world

A subagent starts fresh, with its own prompt and tools. It does not see the coordinator's turns, the researchers' notes or the tool results the coordinator read. Whatever the writer must use has to be in the prompt the coordinator writes. That prompt is the brief.

This design fails in three ways. The findings never reach the writer, a summary drops each source, and two figures that differ only by date look like a conflict. You will see the first fail, then fix it, then see the third.

Do not solve this by sending the whole history. Every request carries it, so each call costs more as it grows, and early facts get buried in the middle of a long input. Send the findings the writer needs and nothing more.

A brief with findings gives a sourced report

The brief holds the task and every finding. Each one has its claim, its evidence, its source and its date. The coordinator starts the writer with the Agent tool, called Task in older releases, and gives the brief as the prompt.

Open the prompt card to read what the writer got. Every line of the report ends with the source and date it came from.

ColleagueWrite the recall report for the power bank.

Writer prompt6 of 6 findings in the brief

Show the result

Task: Write the recall report for the power bank.

Findings from the researchers
- Claim: The cells swell when a separator is thin. Evidence: A teardown found separators under spec. Source: Lab teardown Date: 3 Mar
- Claim: The thin separators came from one batch. Evidence: The batch code matches every failed unit. Source: Supplier audit Date: 5 Mar
- Claim: Units made in March are affected. Evidence: Failures cluster in lots seven to nine. Source: Batch log Date: 6 Mar
- Claim: Forty units swelled in the field. Evidence: Reports came from six countries. Source: Field report Date: 9 Mar
- Claim: No unit has caused an injury. Evidence: No claim was filed. Source: Claims desk Date: 11 Mar
- Claim: Customers can swap a unit for free. Evidence: The offer needs the lot code on the base. Source: Returns desk Date: 12 Mar

How to write
Write one line per finding. Cite each line: end it with its source and date in brackets. If two findings give different figures for the same thing, keep both figures with their dates and do not pick one.

WriterPOWER BANK RECALL REPORT (built only from the researcher findings supplied; the sources give day and month but no…

Show the result

POWER BANK RECALL REPORT (built only from the researcher findings supplied; the sources give day and month but no year)

Findings, one line each:

1. Cells swell when the separator is thin. A lab teardown found the separators under spec. [Lab teardown, 3 Mar]
2. The thin separators came from one batch. The batch code matches every failed unit. [Supplier audit, 5 Mar]
3. Failures cluster in lots seven to nine. [Batch log, 6 Mar]
4. Units made in March are affected. [Batch log, 6 Mar]
5. Forty units swelled in the field. Reports came from six countries. [Field report, 9 Mar]
6. No unit has caused an injury. The supporting evidence is that no claim was filed. [Claims desk, 11 Mar]
7. Customers can swap a unit for free. The offer requires the lot code on the base of the unit. [Returns desk, 12 Mar]

Conflicting figures (both kept, not resolved):
- Scope of the batch: Finding 2 says the thin separators came from one batch [Supplier audit, 5 Mar]. Finding 3 says failures cluster across lots seven to nine [Batch log, 6 Mar]. Whether the affected population is one batch or three lots is not settled by the findings.

Caveats for the reader:
- Finding 4 (March) is not shown directly in its evidence. The cited evidence refers to lots seven to nine, and the link from those lots to March production is not stated in the findings.
- Finding 6 is weak support for its claim. No claim being filed does not establish that no injury occurred. The wording should be treated as unverified.
- Finding 7 is conditional. The free swap depends on the lot code being on the base, so the offer does not cover every unit without qualification.
- The findings do not name the product model, the total number of units affected, or the total units sold. These are needed for a complete recall scope.

6 sources and 6 dates kept of 6.

The brief as written

brief turns the task and the findings into the writer's prompt. The starting version passes the task and ignores the findings, so the writer has nothing to cite.

Findings cost little to pass. Each one is about 40 tokens, so twelve are about 480 tokens. Passing none costs 0 and loses every citation.

Two habits keep the brief lean. Ask each researcher to return only the few fields the writer needs, with the source and date kept on each claim. Tell a subagent what is already covered, so it does not repeat a search the coordinator finished.

starter/handoff.py

1"""The handoff: what the report writer is told, since it knows nothing else."""234def brief(task: str, findings: list[dict[str, str]]) -> str:5 """The writer's whole prompt.6 TODO(workshop): the writer starts fresh and cannot see the findings.7 Pass each one with its claim, evidence, source and date.8 """9 return f"{task}\n\nWrite one line per finding."

What does the writer see of the coordinator's work?

Take the request for the recall report. The coordinator holds six sourced findings. It calls brief with the task and the findings, and the starting version returns only the task.

Predict: What does the writer see of the six findings?

ANone, because a subagent knows only its prompt.
BAll six, because they share the session.

Show the answer

A. A subagent does not inherit the coordinator's context. Pass the findings in the prompt, or they do not exist for the writer.

The report has no sources

This is the same request with the starting handoff. The writer has no findings, so it has nothing to report and asks for the findings. The outcome line is red.

This is a real Claude Haiku 5.5 run through the Agent SDK, recorded once and replayed here.

ColleagueWrite the recall report for the power bank.

Writer prompt0 of 6 findings in the brief

Show the result

Write the recall report for the power bank.

Write one line per finding.

WriterThe writer subagent did not produce a recall report. Its reply, word for word: Blocked. I could not write the power…

Show the result

The writer subagent did not produce a recall report. Its reply, word for word:

Blocked. I could not write the power bank recall report because I have no source material and no working tool to get it.

- The only tool available to me is SubagentHandback. My attempt to run a shell command failed with "No such tool available: Bash. Bash is disabled for this session."
- I was not given any recall notice, product data, or document in the task message, so there is nothing I can cite.
- The working directories I was given (/private/var/folders/57/8pd9jzz53rz3bydfggfv_1x40000gn/T/tmpq092ea7g and /var/folders/57/8pd9jzz53rz3bydfggfv_1x40000gn/T/tmpq092ea7g) were not listed, so I do not know whether they contain the relevant files.
- I have not produced any recall findings, because any claim about the power bank would be unsourced.

To proceed, please do one of the following:
1. Paste the recall notice or source text into the task, or name the file paths I should read, and give me a file-reading tool or enable Bash.
2. Confirm the product (brand, model, and batch or serial range) and the authority the recall came from (for example, CPSC or a manufacturer notice), so the report can be built from a source you provide.

0 sources and 0 dates kept of 6.

Pass the claim, evidence, source and date

The fix writes each finding into the brief as one block with separate fields: the claim, the evidence, the source and the date. It then asks for one line per finding, each ending with its source and date.

Keeping the four fields apart is what lets a source survive the writing. Data and its metadata travel together.

handoff.pygreen lines are what the fix adds

1"""The handoff: what the report writer is told, since it knows nothing else."""234def brief(task: str, findings: list[dict[str, str]]) -> str:5 """The writer's whole prompt: the task, then every finding in fields."""6 lines = "\n".join(7 f"- Claim: {f['claim']} Evidence: {f['evidence']} "8 f"Source: {f['source']} Date: {f['date']}"9 for f in findings10 )1112 return (13 f"Task: {task}\n\n## Findings from the researchers\n{lines}\n\n"14 "## How to write\nWrite one line per finding. Cite each line: end "15 "it with its source and date in brackets. If two findings give "16 "different figures for the same thing, keep both figures with "17 "their dates and do not pick one."18 )

We doChange one setting at a time and predict.

The same findings, two different ends

Use the switch to run the request with the starting handoff, then the fixed one. The card marked "This is where the runs split" shows how many findings the writer was given.

Try the shorter set of six too. The starting handoff keeps none of the findings in either set, and the fix keeps all of them in both.

This part is interactive in the lab: run ./workshop watch passing-context.

Conflicts keep both sources

The twelve findings hold two figures for one thing: 40 swollen units on 9 March and 65 on 18 March. The fixed brief tells the writer to keep both with their dates. Switch to a brief that keeps only the newer figure. The report lists only the 65 and moves the 9 March count to a superseded note.

A date often explains a gap between two figures, so show both. Match the format to the content: a table for finance figures, prose for news and a list for technical facts. Put key findings first under clear headings, because a long input is read least in the middle.

This part is interactive in the lab: run ./workshop watch passing-context.

Try it: handoff and findings

Change one setting at a time. Pick the shorter or the longer set of findings, then switch between the starting handoff and the fix.

Every combination is a recorded run, so this works with no internet.

This part is interactive in the lab: run ./workshop watch passing-context.

Passing findings to a subagent in the Agent SDK

The writer is defined with AgentDefinition: a description, a prompt, an empty tool list and a model. The coordinator starts it with the Agent tool, so that tool must be in the allowed tools. The harness runs the request through the SDK's query() and reads the prompt the writer was given from the recording.

The run starts in an empty folder, and the writer has an empty tool list, so any tool it tries is refused. A session resumed with fork_session branches into a new session, to try an alternative from one history. This is a real Claude Haiku 5.5 run.

app/agent.pyfile: 196 lines

···27 lines not shown28 "word for word with nothing added. When the writer replies, return its "29 "report word for word."30)31WRITER = (32 "You write a recall report for a colleague. Use only what you are "33 "given, and cite a source for each claim."34)353637def writer() -> dict[str, AgentDefinition]:38 """The one subagent the coordinator can spawn: it has no tools."""39 return {40 "writer": AgentDefinition(41 description="Writes the recall report from the prompt it gets.",42 prompt=WRITER,43 tools=[],44 model="haiku",45 )46 }474849def seen(date: str, text: str) -> bool:50 """Whether a date like '3 Mar' is written in the text, either way round."""51 day, month = date.split()52 pattern = (···144 lines not shown

ColleagueWrite the recall report for the power bank.

Writer prompt12 of 12 findings in the brief

Show the result

Task: Write the recall report for the power bank.

Findings from the researchers
- Claim: The cells swell when a separator is thin. Evidence: A teardown found separators under spec. Source: Lab teardown Date: 3 Mar
- Claim: The thin separators came from one batch. Evidence: The batch code matches every failed unit. Source: Supplier audit Date: 5 Mar
- Claim: Units made in March are affected. Evidence: Failures cluster in lots seven to nine. Source: Batch log Date: 6 Mar
- Claim: Forty units swelled in the field. Evidence: Reports came from six countries. Source: Field report Date: 9 Mar
- Claim: No unit has caused an injury. Evidence: No claim was filed. Source: Claims desk Date: 11 Mar
- Claim: Customers can swap a unit for free. Evidence: The offer needs the lot code on the base. Source: Returns desk Date: 12 Mar
- Claim: The safety agency must be told within ten days. Evidence: A swelling battery is a reportable hazard. Source: Agency notice Date: 13 Mar
- Claim: A retest of the swap units passed. Evidence: Fifty units held their charge for a week. Source: Safety test Date: 15 Mar
- Claim: The supplier accepts the fault. Evidence: They will pay for the swap. Source: Supplier letter Date: 16 Mar
- Claim: Retailers hold a few thousand units. Evidence: Stock counts came from three chains. Source: Retailer call Date: 17 Mar
- Claim: Sixty-five units swelled in the field. Evidence: Reports came from nine countries. Source: Field update Date: 18 Mar
- Claim: Shipping of the lots is on hold. Evidence: The hold started on the tenth. Source: Shipping log Date: 19 Mar

How to write
Write one line per finding. Cite each line: end it with its source and date in brackets. If two findings give different figures for the same thing, keep both figures with their dates and do not pick one.

WriterPOWER BANK RECALL REPORT (findings as supplied; no independent verification) 1. Cells swell when the separator is…

Show the result

POWER BANK RECALL REPORT (findings as supplied; no independent verification)

1. Cells swell when the separator is thin, and a lab teardown found separators under spec. [Lab teardown, 3 Mar]
2. The thin separators came from one batch, and the batch code matches every failed unit. [Supplier audit, 5 Mar]
3. Units made in March are affected, with failures clustered in lots seven to nine. [Batch log, 6 Mar]
4. Forty units swelled in the field, with reports from six countries. [Field report, 9 Mar]
5. No unit has caused an injury. Evidence cited is only that no claim was filed, which does not by itself establish that no injury occurred. [Claims desk, 11 Mar]
6. Customers can swap a unit for free, but the offer requires the lot code on the base. [Returns desk, 12 Mar]
7. The safety agency must be notified within ten days, because a swelling battery is a reportable hazard. [Agency notice, 13 Mar]
8. A retest of the swap units passed: fifty units held their charge for a week. The source does not state how many units were tested in total. [Safety test, 15 Mar]
9. The supplier accepts the fault and will pay for the swap. [Supplier letter, 16 Mar]
10. Retailers hold a few thousand units, based on stock counts from three chains. [Retailer call, 17 Mar]
11. Sixty-five units swelled in the field, with reports from nine countries. [Field update, 18 Mar]
12. Shipping of the lots is on hold, and the hold started on the tenth. [Shipping log, 19 Mar]

CONFLICTING FIGURES (both kept, not reconciled):
- Field swelling count: 40 units from six countries [Field report, 9 Mar] versus 65 units from nine countries [Field update, 18 Mar]. The 18 Mar figure is the later one, but no source explains the difference.

CAVEATS:
- The newest finding is dated 19 Mar, and today is 2026-10-15. Status of the shipping hold, swap program, supplier payments, and agency notice may have changed since then and needs current confirmation.
- Item 12 gives "the tenth" without a month; I have not assumed it is 10 March.

12 sources and 12 dates kept of 12.

You doFix the starting code, then test yourself.

You do: pass the findings

Copy the starting code and open work/passing-context/handoff.py. brief() keeps the task but passes no findings, so the writer starts with nothing to cite.

Terminal

./workshop start passing-context
./workshop check passing-context
./workshop watch passing-context

The checks want every claim, its evidence, source and date in the brief, and an instruction to cite each line. When two sources disagree, both figures must arrive with their dates.

Check your understanding

Answer each question, then read why every option is right or wrong. The wrong options are the mistakes engineers make on the job.

1. A writer subagent returns a fluent recall report with no sources. The coordinator read six sourced findings earlier in its session and then asked the writer to write the report. What is the root fix?

AAsk the writer to be more careful about sources, since it has the same session as the coordinator.
BPaste the six findings, each with its source and date, into the writer's prompt.
CRaise the writer's turn limit from 4 to 12 so it can search for the sources itself.
DAsk a second writer to edit the report and add the missing citations afterwards.

Show the answer

Answer: B

A The writer does not share the session. Care cannot cite what it has never seen.
B Correct. A subagent knows only its prompt, so whatever the writer must cite has to be in it.
C More turns let it guess longer. The sources are in the coordinator, and a limit does not move them.
D A second writer starts just as fresh, with no findings. It can only invent a citation.

2. A subagent repeats a search the coordinator finished an hour ago, and 9 of its 12 queries match earlier ones. The coordinator's history holds the results. What fixes the repeat?

AGive the subagent read access to the coordinator's conversation so it can look for itself.
BTell the coordinator to run every search twice so one copy is always in the subagent's cache.
CAsk the subagent to write shorter queries, since long queries are likely to match older ones.
DPass the earlier findings in the subagent's prompt and tell it what is already covered.

Show the answer

Answer: D

A A subagent starts with a fresh context and does not see the coordinator's turns.
B A cache is not a context. The duplicate work doubles and the subagent still does not know the results.
C Query length is not the cause. The subagent does not know what was already searched.
D Correct. The subagent has no history, so the prompt is the only place the earlier work can reach it.

3. A coordinator pastes 12 findings into the writer's prompt as one paragraph of prose. The report cites 4 sources and gets the dates wrong for 7 claims. What change keeps the metadata?

AKeep each claim, its evidence, its source and its date as separate fields in the brief.
BAsk the coordinator to write a shorter paragraph so the writer can hold all 12 facts at once.
CTell the writer to add the dates from memory when a claim has none, to keep every line uniform.
DMove the source names to the start of the paragraph, before the first claim.

Show the answer

Answer: A

A Correct. Separate fields let the source and date travel with the claim, so nothing has to be guessed from prose.
B Shorter prose drops more detail. The loss comes from blending fields, not from length.
C Memory is how an invented date gets into a report. The date has to be in the brief.
D Moving the names does not tie each one to its claim. The link is lost either way.

4. Select two statements that are true of a subagent started by a coordinator.

AIt starts fresh, with none of the coordinator's turns.
BIt sees the findings the coordinator read, because both work on one request.
CIt learns about the task only from the prompt it was given.
DIt reads the coordinator's earlier tool results when it needs a source to cite.

Show the answer

Answer: A, C

A Correct. The coordinator's turns and tool results are not copied into it.
B They work on one request but hold separate contexts.
C Correct. Anything the coordinator read and did not write into the brief is missing for the subagent.
D Tool results stay in the coordinator's context. The subagent only sees what the brief repeats.

5. A coordinator merges 12 findings into one summary paragraph for the writer. The report reads well but a reviewer cannot trace 9 of its claims to a source. What should the coordinator keep?

AA longer summary, so the 9 untraceable claims each get a full sentence of their own.
BOnly the claims that more than one researcher found, since those need no source.
CThe mapping from each claim to its source, passed along with the claim.
DA note at the top of the report saying the claims come from trusted researchers.

Show the answer

Answer: C

A A longer summary still has no source attached. The mapping is what is missing.
B Agreement between researchers is not a citation. A reviewer still has nothing to check.
C Correct. A claim with its source can be checked. A summary without the mapping cannot.
D A general note names no source. Each claim needs its own.

6. A lab report says 12 percent of units failed, while a retailer call says 15 percent. A reviewer asks the writer which figure is right. What should the report do?

AShow both figures, each with its source, and say which numbers conflict.
BReport the 15 percent, since the higher figure is the safer one for a recall.
CAverage the two and report 13.5 percent with no sources, to keep the line short.
DDrop both figures and write that failures were reported, to avoid taking a side.

Show the answer

Answer: A

A Correct. The reader can judge the gap only when both figures and their sources are visible.
B Choosing by size hides the other source. The reader cannot see the conflict.
C An average belongs to neither source and cannot be checked.
D Dropping both loses the evidence. The report should show the conflict.

7. A report holds two figures for swollen units: 40 from a 9 March field report and 65 from an 18 March field update. A reviewer calls it a contradiction. What explains it?

AOne of the two sources is wrong, so the writer should keep the newer one and drop the other.
BThe dates differ, so the later figure may count units that swelled after the first report.
CThe writer rounded one of them, so the figures should be averaged to 52.5.
DThe researchers used different search tools, so the figures cannot be compared at all.

Show the answer

Answer: B

A Nothing says either is wrong. Dropping one throws away the trend.
B Correct. A date often explains a gap. Keeping both dates lets the reader see that.
C An average hides both the dates and the two sources.
D Different tools do not make two dated counts incomparable. The dates are the difference.

8. A report holds quarterly financial figures from 4 sources. Select two rules for presenting them.

AWrite them as flowing prose, since one format suits every kind of content.
BUse a table, since numbers are easier to compare across rows and columns.
CPut the sources in a single list at the bottom, since rows read more cleanly without them.
DKeep the source with each row, so every figure can be traced.

Show the answer

Answer: B, D

A A table suits figures, prose suits narrative. One format does not suit both.
B Correct. Finance figures are compared by row and column, which is what a table is for.
C A list at the end breaks the link between a figure and its source.
D Correct. Without a source beside the row, the reader cannot check a number.

9. A coordinator passes a 60,000 token input to the writer. The 2 findings that matter most sit in the middle and the report misses both. What helps most?

ALeave them in the middle and ask the writer to read the whole input twice.
BMove to a model with a larger window, so 60,000 tokens no longer counts as long.
CAdd a sentence at the end saying the middle of the input is important.
DPut the key findings at the start under clear headings and trim the rest.

Show the answer

Answer: D

A Asking twice does not change where the model attends. The position is the problem.
B A larger window holds more, but key facts in the middle are still missed.
C A sentence at the end does not bring the middle findings forward.
D Correct. Models read the edges of a long input most reliably, so headings and position help.

10. A researcher returns 40 fields per finding and the writer uses 5 of them. The report still loses dates. What should the researcher return?

AAll 40 fields, since the writer can decide which to use for its report.
BOnly the claims, since the source and date are kept in the coordinator's notes.
CThe few fields the writer needs, including the source and the date with each finding.
DA one-line summary per finding, to cut the result from 40 fields to 1.

Show the answer

Answer: C

A Extra fields bury the few that matter and fill the context.
B The writer does not see the coordinator's notes. The metadata must travel with the claim.
C Correct. A smaller result keeps the context lean, and the date and source still travel with the claim.
D A summary drops the source and date that the report needs.

11. A report passes through 3 rounds of summary. A finding of 12.5 percent comes out as about 12 percent, and the source is gone. What prevents it?

AAsk each round to summarize more carefully, since the wording is the source of the loss.
BAdd a fourth round that compares the summary with the first to catch any drift.
CRaise the context window so all 3 rounds fit without any trimming.
DKeep the facts in a block outside the summary and pass them unchanged.

Show the answer

Answer: D

A Careful wording still rounds and drops. The fix is to stop re-summarizing the facts.
B The first summary has already lost the detail. A comparison cannot restore it.
C Fit is not the issue. Each round still blurs the figure.
D Correct. Each summary rounds and drops detail, so the exact figures and sources stay in a block of their own.

12. A coordinator keeps a long history of 80 turns and sends every turn to each new subagent. Select two effects of a long history.

AEvery request carries it, so each call costs more as the history grows.
BOlder turns are read better than new ones, since the model reads from the start.
CA bigger window removes the cost, since nothing has to be trimmed any more.
DOld detail is buried, so early facts are easier to miss in the middle.

Show the answer

Answer: A, D

A Correct. The whole history is sent with each request, so cost and delay grow with it.
B Attention to the middle falls off. Age alone does not make a turn clearer.
C A bigger window holds more, but the cost of carrying it stays.
D Correct. Facts placed early in a long input compete with everything after them.

Play: predict the output

This handoff keeps each finding whole but trims the list to save tokens.

python

def brief(task: str, findings: list[dict[str, str]]) -> str:
    lines = "\n".join(
        f"- {f['claim']} ({f['source']}, {f['date']})" for f in findings[:5]
    )
    return f"{task}\n\n{lines}\n\nCite the source and date of each line."

Predict: Seven findings come back, and the regulator's notice is the seventh. What does the report say about the regulator?

ANothing. The writer never saw the seventh finding.
BIt mentions the notice, since the researchers found it.

Show the answer

A. A writer can cite only what its prompt holds. To save tokens, cut the fields a finding carries, never the findings themselves.

References

Agent SDK subagents: a subagent starts fresh, so its prompt is all it knows.
Citations: how the API ties each claim to the passage that supports it.
How we built our multi-agent research system: how a lead agent briefs each subagent with a task, a format and sources.
Effective context engineering: why a brief should hold only what the next agent needs.

Conclusions

A subagent does not inherit context, so its prompt must carry everything it needs.
Each finding travels as claim, evidence, source and date, kept together.
A summary hides conflicts and sources, so pass the findings themselves.

You can now write a brief that keeps provenance alive from the researchers to the final report.

Brief

The prompt a coordinator writes for a subagent

Provenance

Where a claim came from, and when

Finding

One claim with its evidence, source and date

Fresh context

What a subagent starts with: its own prompt and tools, none of the coordinator's turns