Week 3 slides: the harness around the loop
← → to move, F for full screen, N for speaker notes
AI in Research · Week 3 · October 14, 2026
The harness around the loop
What Codex and Claude Code add to the loop you built last week.
This week
One agent, many layers: progressive disclosure · AGENTS.md · skills and plugins · tools and MCP, and other agent protocols · a short look at control
Next week · Oct 21
Many agents: subagents · workflows vs agents · multi-agent systems, when they help or hurt · how agents talk to each other
class.xhelio.ai/week-3
Week 2 in one API call
Stateless
JSON in, JSON out
Every call sends everything: instructions, tools, the whole conversation. The server remembers nothing.
One stream
The model sees tokens
The server flattens your JSON into one token stream with role markers. Tools are text in it too.
Two outputs
Text, or a tool call
A tool call is tokens in a trained format. Strict mode masks the softmax so the JSON is valid.
The model never runs anything. Your program reads the call, runs it, and sends the result back.
What every call costs
| gpt-6-astra, $ per million tokens | Price | Why |
|---|---|---|
| Cache read | $1 | keys and values already computed |
| Fresh input | $10 | one parallel pass |
| Output, including hidden reasoning | $50 | one full pass per token |
Stable things first: the cache only hits on an exact prefix, so tools and instructions go before the conversation.
Context only grows: a 30-turn run cost $19 without caching and $5 with it.
Keep it small: compaction, subagents and memory files, at the risk of forgetting.
The loop you built, and today's question
Codex and Claude Code run this same loop. Today is the layers around it:
SYSTEM_PROMPT: what the model is toldTOOLS: what it can ask forrun_bash: what actually happens
For each layer, ask: does it enter the context, when, and what does it cost? Text in the context persuades; code outside it enforces.
The idea of the week: progressive disclosure
Week 2: every call resends the whole context, and the context is finite and paid for.
So a good harness keeps a short index in the context, and lets the agent open the rest with a tool call when it needs it.
Keep the index in the context. Keep the library on disk.
Like a textbook
The table of contents is always open. You read a chapter when you need it, and the appendix almost never.
The failure mode
A vague index entry: the agent never opens the right chapter.
Three levels, as skills do it
Level 1 · always
Name + description
About 100 tokens per skill.
A hundred skills cost less than one long AGENTS.md.
Level 2 · on trigger
The SKILL.md body
Read with a tool call when the task matches. Keep it under about 5,000 tokens.
Level 3 · when needed
Other files
References read only if the body points there. Scripts are run, not read: their code never enters the context, only their output.
So a skill can carry far more than any context window.
Where you will meet it today
Keep a short index in the context. Keep the library on disk.
| Where | Always in context | Loaded on demand |
|---|---|---|
| Skills | name + description | body, references, script output |
| Tool search | tool names | a tool's full schema |
| AGENTS.md | the short file | the docs it points to |
| Memory | the index | each note |
| Subagents (next week) | a short report | — the work stays in the subagent |
What is in the context before you type a word
Stable things first, changing things last: the same order that makes the prompt cache hit (week 2).
In a real Claude Code or Codex session the top five layers are often tens of thousands of tokens, paid on every call.
AGENTS.md: a README for agents
A plain Markdown file in your project. The harness pastes it into the context at the start of every session.
| Where | Applies to |
|---|---|
~/.codex/AGENTS.md, ~/.claude/CLAUDE.md | you, in every project |
repo/AGENTS.md | everyone working in this repo |
repo/analysis/AGENTS.md | work inside that folder |
Files closer to your work are read later, so they win a conflict. Codex stops at 32 KiB in total.
AGENTS.md
An open standard, now at the Linux Foundation. Read by Codex, Cursor, Copilot, Gemini CLI, Zed and many more; in 60,000+ repos.
CLAUDE.md
Claude Code's own name. Since September 2026 it also reads AGENTS.md when no CLAUDE.md exists.
What a research group's AGENTS.md might say
AGENTS.md
Good lines
Commands, conventions, things a newcomer gets wrong, pointers to longer docs.
Bad lines
The whole README, style essays, what the code already enforces, anything stale.
Every line is resent on every call. Add one when the agent makes the same mistake twice.
Skills: a folder of know-how, loaded when needed
.agents/skills/
A folder. Nothing to install, no server to run.
SKILL.md
The frontmatter is the trigger. The body is the instructions. The other files are there if the body points to them. An open standard since December 2025: one folder works in Claude Code, Codex, Copilot, Cursor and more.
Installing skills: the skills CLI
| Agent | Project folder | Your user folder |
|---|---|---|
| Claude Code | .claude/skills/ | ~/.claude/skills/ |
| Codex, Cursor, OpenCode | .agents/skills/ | ~/.agents/skills/ (Codex) |
One command copies a skill folder from GitHub into every agent you use; it detects them, about 80 in all.
Directory: skills.sh. A skill is just a folder, so git clone works too.
Read a skill before installing it: its scripts run on your computer. The CLI sends anonymous usage data; DISABLE_TELEMETRY=1 turns it off.
Plugins: everything above, in one folder you install
telegram/
A plugin bundles MCP servers, skills, hooks and subagents. Install it once; they all arrive together.
A marketplace is a git repo that lists plugins. Codex has plugins too, since March 2026.
Claude Code's own Telegram bridge is a plugin like this: an MCP server and a skill. It is also your homework.
Agent Plugins 1.0: one plugin format for many agents
An Agent Plugin
A vendor-neutral package for the two things everyone agrees on: skills and MCP servers.
Everything else, such as hooks, permissions and installation, stays each agent's own, in a reverse-domain folder.
Steering committee: Amazon, Cursor, Microsoft, OpenAI, Vercel. Published July 2026, launched August 6, 2026. Launch clients: ChatGPT and Codex, Cursor, GitHub Copilot, Kiro, VS Code; since then OpenClaw, OpenHands and others. Claude Code is not one: it keeps its own format (previous slide).
agent-plugins.org · github.com/agentplugins/agent-plugins-spec
Which one should I use?
| Holds | Who triggers it | Use it for | |
|---|---|---|---|
| AGENTS.md | a few rules | always on | conventions every task needs |
| Skill | instructions + files + scripts | the model, by description | a procedure you repeat: a fit, a figure style, a submission |
| MCP server | tools backed by a program | the model, by tool call | live systems: an archive, a database, an API with a login |
| Slash command | a saved prompt | you, by typing /name | things you start on purpose: /review, /deploy |
| Plugin | a bundle of the above | installed once | sharing a whole setup with your group |
A good default: start with AGENTS.md, turn repeated procedures into skills, reach for MCP only when you need a running program.
What ships in a coding agent
| Job | Claude Code | Codex |
|---|---|---|
| Run a command | Bash | shell |
| Read a file | Read (also images, PDFs) | through shell; view_image |
| Change a file | Edit, Write | apply_patch |
| Search the web | WebSearch, WebFetch | web_search |
| Plan and track steps | plan mode, task list | update_plan |
| Hand off a sub-task | Agent | subagents |
| Load more on demand | Skill, ToolSearch | skills |
Plus every tool from every connected MCP server. Names change between versions; the jobs don't.
Write tools for a reader with no context
| Hard for an agent | Easy for an agent | |
|---|---|---|
| Name | get_data | omni_solar_wind |
| Description | "Gets data." | "Hourly solar wind at Earth (OMNI), 1963 to now. Not for spacecraft-frame data." |
| Parameters | t1, t2 | start_utc, end_utc (ISO 8601), with an example |
| Output | 86,400 raw rows | a summary; the full table saved to a file |
| Errors | Error 400 | "No 1-minute data before 1995. Try resolution='1h'." |
| Scope | 20 thin wrappers around an API | a few tools that each finish a whole task |
Everything a tool returns is resent on every later call. Test a tool the way you test a student's instructions: give it to an agent and read the transcript.
Anthropic Engineering, "Writing effective tools for agents — with agents", September 2025
The problem MCP solves
Without a standard, every harness writes its own connector to every service.
With MCP (Model Context Protocol), each service writes one server, each harness writes one client: 4 + 5.
Released by Anthropic in November 2024, given to the Linux Foundation's Agentic AI Foundation in December 2025. Supported by Claude, ChatGPT, Codex, Cursor, VS Code, Copilot and more.
What MCP is, in one sentence
An agreed set of JSON messages that an AI application and a separate program use to say "what can you do?" and "do this".
It is
A protocol: rules for messages, like HTTP or USB. Anyone can implement either side, in any language.
It is not
A model feature, a library or a product. It is the contract between two programs, so either side can be swapped.
Modelled on
The Language Server Protocol: one Python "language server" works in every code editor. One MCP server works in every agent.
Anthropic, November 2024 · adopted by OpenAI, Google and Microsoft in 2025 · given to the Linux Foundation's Agentic AI Foundation, December 2025 · current spec: 2026-07-28
Host, client, server
The model never speaks MCP. The harness asks each server for its tools and shows them to the model as ordinary tool schemas.
Exactly what is in the protocol
| Layer | What it defines | Required? |
|---|---|---|
| Base protocol | JSON-RPC 2.0 messages: requests, results, errors, notifications; a _meta block on every request | yes |
| Versioning | every request names its protocol version; server/discover lists what the server supports | yes |
| Message patterns | request–response; multi-round-trip (the server needs input); subscribe and notify | yes |
| Transports | how bytes move: stdio (a local process) or Streamable HTTP | pick one |
| Authorization | OAuth 2.1 login for HTTP servers; stdio servers read keys from the environment | for HTTP |
| Server features | tools, resources, prompts | any of them |
| Client features | elicitation: ask the user something (sampling and roots: deprecated) | optional |
| Utilities | progress, cancellation, logging, argument completion, pagination, caching hints | optional |
| Extensions | opt-in: Tasks (long jobs), MCP Apps (interactive UI), Skills over MCP | opt-in |
modelcontextprotocol.io/specification/2026-07-28
Four message shapes, and that's all
Request · client to server
Notification · no reply expected
Result · same id
Error · same id
The id ties each answer to its question, like call_id in week 2, so many requests can be in flight at once. Since July 2026 the protocol is stateless: every request carries everything the server needs.
A whole exchange on the wire
Discover (optional) → list the tools once, cache them for ttlMs → call as often as the model asks. Your harness turns step 2 into tool schemas and step 3's text into a tool result.
A tool, field by field
The definition (in tools/list)
name | unique per server, letters, digits, _ - . |
title | for people, optional |
description | what the model reads to decide |
inputSchema | JSON Schema of the arguments |
outputSchema | optional: shape of structured results |
annotations | hints (read-only? destructive?) — untrusted unless the server is |
The result (of tools/call)
content | a list of text, image, audio, a resource link or an embedded resource |
structuredContent | JSON matching outputSchema |
isError | true: the tool ran and failed; the text says why |
Two kinds of error: an unknown tool is a protocol error; a bad date is a tool error with isError: true, sent to the model "to enable self-correction".
Tools, resources, prompts: who decides to use them
| Feature | What it is | Methods | Who decides |
|---|---|---|---|
| Tools | functions the model can call | tools/list, tools/call | the model |
| Resources | data identified by a URI: a file, a table, a dataset's description | resources/list, resources/read | the application |
| Prompts | reusable message templates, often shown as slash commands | prompts/list, prompts/get | the user |
Plus subscriptions/listen: an open stream on which the server announces changes, such as notifications/tools/list_changed.
In practice almost every server offers tools, and support for resources and prompts varies between hosts.
When the server needs to ask the user something
1 · The server answers "not yet"
2 · The client asks, then retries
A server never sends requests. It returns input_required; the client shows a form to the user (not the model), and retries with the answers and a new id.
Two ways to carry the messages
stdio · on your computer
The client starts the server as a child process and writes one JSON message per line to its stdin; replies come back on stdout.
Never print to stdout in a stdio server: anything that isn't an MCP message breaks the protocol. Logs go to stderr. Close stdin to shut it down. Keys come from environment variables.
Streamable HTTP · over the network
Each message is an HTTP POST to one endpoint; the reply is JSON, or a stream of events for long answers.
The protocol version and method are mirrored into headers (MCP-Protocol-Version, Mcp-Method) so proxies can route requests. Login with OAuth 2.1. The older HTTP+SSE transport is deprecated.
The messages are identical on both; only the delivery differs. Your homework server uses stdio.
An MCP server in a dozen lines
omni_server.py
Connect it
The function name becomes the tool name, the docstring the description, the type hints the schema.
The catch: every tool schema rides along on every call
55,000
tokens of tool schemas from 5 common MCP servers (58 tools), before you type anything. GitHub alone: 26,000.
Anthropic has seen 134,000 before optimizing.
Two fixes
Tool search. Only names are listed; full schemas load when the model searches for them. −85% tokens, and better tool choice (49% → 74%).
Code instead of calls. The model writes a script that calls the tools; only what it prints enters the context. 150,000 → 2,000 tokens in Anthropic's example.
Tool search is on by default in Claude Code; OpenAI's API has tool_search too.
Anthropic Engineering: "Introducing advanced tool use", Nov 24, 2025; "Code execution with MCP", Nov 4, 2025
The protocol landscape: one per connection
| Connects | Protocol | From |
|---|---|---|
| agent ↔ tools and data | MCP | Anthropic, now at the Agentic AI Foundation |
| agent ↔ lab instruments, machines | MHS, Model Hardware Standard | Anthropic, research preview, Aug 2026 |
| code editor ↔ coding agent | ACP, Agent Client Protocol | Zed and JetBrains, 2025 |
| agent ↔ agent | A2A (next week) | Google, now at the Agentic AI Foundation |
| agent ↔ the app a person uses | AG-UI | CopilotKit, 2025 |
| agent ↔ shops and payments | Agentic Commerce Protocol (also "ACP"); UCP and AP2 | OpenAI and Stripe; Google |
| packaging, not wire protocols | AGENTS.md, Agent Skills, Agent Plugins | Parts 2 and 3 |
They share a shape: JSON messages, a way to discover what the other side can do, and a human approval step for risky actions.
MHS: agents that operate lab instruments
"A shared specification for AI agents to safely operate physical devices": a standard driver that says what a device can measure, what can be adjusted, and which limits will be enforced.
Not built on MCP: MCP is one of three ways in. Research preview since August 27, 2026, with HHMI Janelia; to be open-sourced later.
Partner-reported
QuEra: an agent relocked a laser in 99.3% of 700 trials, against 58% for hand-written scripts.
anthropic.com/news/model-hardware-standard-research-preview · modelhardwarestandard.com
ACP: any coding agent, inside any editor
editor ⇄ agent, JSON-RPC over stdio
Like LSP did for languages: the editor speaks ACP once, and any agent works in it.
The editor starts the agent as a subprocess, like an MCP stdio server, and owns the files and the approval buttons.
Zed and JetBrains, since August 2025. 13 editors (Zed, JetBrains IDEs, VS Code, Neovim, Emacs, …) and 47 agents (Claude, Codex, Gemini CLI, Copilot, …).
agentclientprotocol.com · zed.dev/acp
An agent with bash can do anything you can
Your week 2 harness runs whatever command the model writes, as you, with your files, keys and network.
July 2025
Replit's coding agent deleted a startup's production database during an explicit code freeze, then misreported what it had done.
It had been told repeatedly not to change anything.
Most mistakes are not malice. They are a confident model, a wrong guess, and no fence.
Three fences, from polite to absolute
Permissions
Ask a human
Before an action runs, the harness checks a rule list: allow, ask you, or deny.
Enforced by the harness.
Hooks
Ask your code
Your script runs at a fixed point in the loop and can block the action, or add a message.
Enforced by your script.
Sandbox
Ask the OS
The operating system stops the process from touching files or network outside a boundary.
Enforced by the kernel, whatever the command is.
None of the three is text in the context. The model can't talk its way past them. The details, with examples, are in the week 3 reading (sections 7–9).
The lethal trifecta
"If your agent combines these three features, an attacker can easily trick it into accessing your private data and sending it to that attacker."
A research agent that reads papers from the web, in your home folder, with internet access, has all three.
Remove one leg. Usually the easiest is the way out: no network in the sandbox.
Simon Willison, "The lethal trifecta for AI agents", June 16, 2025
"Never touch data/raw", four ways
| Layer | Who enforces it | Can the model get past it? | Gaps |
|---|---|---|---|
| AGENTS.md line | the model itself | yes, by ignoring it | followed most of the time |
| Permission rule | the harness, or you | only if you click yes | covers named tools only |
| Hook | your script | no | only the cases you thought of |
| Sandbox | the operating system | no | coarse: folders and network |
Use them together: the instruction explains, the hook catches, the sandbox bounds.
Read before the homework: permission modes, Codex and Claude Code sandboxes, prompt injection cases, and hook examples: class.xhelio.ai/week-3/reading.
One more tool: start another agent
To the main agent, a subagent is just a tool call. Inside, it is a whole new loop.
Only the report comes back: progressive disclosure for work.
Claude Code: .claude/agents/*.md. Codex: .codex/agents/*.toml. Each sets a prompt, tools, a model.
The whole picture: when does it enter the context?
Always, every call
- system prompt
- tool schemas, MCP included
- AGENTS.md
- skill names + descriptions
- memory index
Keep it short. You pay for it on every trip.
On demand
- skill body and files
- deferred tool schemas
- docs AGENTS.md points to
- memory notes
- a subagent's report
Make the index entry good, or it is never opened.
Never
- permission rules
- hooks
- the sandbox
- a script's source code
- a subagent's own work
The only layers that enforce.
Homework: your research, from your phone
1
Build two MCP servers as plugins: Telegram, and one for your research. Both also work in Claude Code or Codex.
2
Teach your harness to load plugins: start their MCP servers, list their skills.
3
Ask a research question from your phone. Only your chat ID gets in; you approve each command by reply.
Your harness keeps just the loop and bash. Everything else can come as a plugin. Due before class, Wed Oct 21 · class.xhelio.ai/week-3/homework
Takeaways
- The context is finite: progressive disclosure. A short index in context, the library on disk.
- AGENTS.md for a few rules, skills for procedures (
npx skills add), plugins to bundle them. - A tool is a prompt and a function. MCP is four message shapes and a handful of methods; anyone can ship a server.
- Text persuades; code enforces. Permissions, hooks and sandboxes: read the details before you run an agent with bash.
- Untrusted content + your data + a way out = the lethal trifecta. Cut one leg.
Further reading for this week: class.xhelio.ai/week-3/reading. Next week: many agents.