Week 3 · Further reading
The harness around the loop, in more depth
The slides keep to the main ideas. This page has the details behind them, with sources, for when you build your homework or want to go further. Facts were checked on October 13, 2026. These tools change monthly, so when something here disagrees with the official docs, trust the docs.
1. Tools
A tool has two halves
The schema (name, description, JSON parameters) is text the model reads, sent with every call. The function is ordinary code in your harness; the model never sees it, only what it returns. So the model picks a tool by its name and description, and learns what happened only from the returned text.
Why not only bash?
Bash can do anything you can do in a terminal, and models have seen millions of shell sessions in training. Production harnesses still add a few dedicated tools, for safety and tokens more than capability:
- Finer permission: allow
Readeverywhere, but ask beforeBash. - Cleaner output: a file with line numbers instead of terminal noise.
- Reviewable edits: Codex edits through
apply_patch, which takes a diff. - Guard rails in code: Claude Code's
Editrefuses to change a file the agent hasn't read in this session.
Rule of thumb: bash for reach; a dedicated tool for anything the agent does dozens of times a session, or anything you want to permit separately.
The returned text is a prompt too
An error like Error 400: bad request makes the agent guess, retry or give up.
No 1-minute OMNI data before 1995. Try resolution="1h", or a start after 1995-01-01. tells it what to do next,
saving a whole trip around the loop. And because the context only grows, a 50,000-token dump read once is paid for on
every remaining call. Cap long outputs, say how much was cut, and save the full result to a file.
Where a tool runs
| Kind | Runs | Examples |
|---|---|---|
| Client tool | in your harness, on your computer | bash, read a file; your loop sees every call and can refuse it |
| Server tool | at the model provider, inside the same API call | OpenAI's web_search; Anthropic's web search and code execution |
| MCP tool | in a separate program, local or remote | any MCP server; written once, usable from any harness |
Anthropic Engineering, "Writing effective tools for agents — with agents", September 2025.
2. MCP, the Model Context Protocol
Released by Anthropic in November 2024 and given to the Linux Foundation's Agentic AI Foundation (AAIF) in December 2025, alongside OpenAI's AGENTS.md and Block's goose. Hosts include Claude, ChatGPT (developer mode), Codex, Cursor, VS Code and Copilot.
What a server offers, and who decides
| Primitive | What it is | Who decides to use it |
|---|---|---|
| Tools | functions the model can call | the model |
| Resources | data the app attaches to the context: a file, a table | the application |
| Prompts | reusable templates, often shown as slash commands | the user |
In the other direction, a server can ask the user a question mid-task (elicitation). The July 2026 spec deprecated sampling, roots and logging; they keep working until at least July 2027. In practice, almost every host and server uses tools; the rest is supported unevenly.
On the wire
MCP messages are JSON-RPC: a method, parameters, and an id that ties the reply to the request. Two messages do most of the work:
→ {"jsonrpc":"2.0", "id":1, "method":"tools/list"}
← {"result": {"tools": [{"name": "omni_solar_wind",
"description": "Hourly solar wind at Earth...",
"inputSchema": {"type": "object", "properties": {...}}}]}}
→ {"jsonrpc":"2.0", "id":7, "method":"tools/call",
"params": {"name": "omni_solar_wind",
"arguments": {"start_utc": "2024-05-10", "end_utc": "2024-05-12"}}}
← {"result": {"content": [{"type": "text", "text": "Peak speed ..."}]}}
The harness turns each tools/list entry into an ordinary tool schema for the model, and appends each tools/call result as the tool's output. The model never speaks MCP.
Shortened for reading: in the 2026-07-28 protocol every request also carries a _meta block with
io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities (required) and
io.modelcontextprotocol/clientInfo (recommended), and every result has a resultType: "complete", or
"input_required" when the server needs the user to answer something first (it then lists inputRequests, and the client
retries with inputResponses). There is no session: a client may call server/discover first, but doesn't have to.
Tool errors come back as results with isError: true so the model can correct itself; an unknown tool is a JSON-RPC error.
The 2026-07-28 spec
- Stateless: no more
initializehandshake or session id; each request carries its protocol version and capabilities. - Transports: stdio (the host starts the server as a local process) and Streamable HTTP (remote). The old HTTP+SSE transport is deprecated.
- Extensions, negotiated when both sides support them: Tasks for long-running work, and MCP Apps (January 2026), tools that return an interactive UI.
- Authorization follows OAuth 2.1; remote servers log you in through the browser.
What tool schemas cost, and the fixes
Five common MCP servers (58 tools) add about 55,000 tokens of schemas before you type anything; GitHub's alone is about 26,000. Tool choice also gets less accurate past roughly 30 to 50 tools. Two fixes, both progressive disclosure:
- Tool search: only names are listed, and full schemas load when the model searches. Anthropic measured 85% fewer tokens and better tool choice (49% → 74% for Opus 4). On by default in Claude Code; OpenAI's API has
tool_searchwithdefer_loading. - Code instead of calls: the model writes a script that calls the tools, and only what it prints enters the context: 150,000 → 2,000 tokens in Anthropic's example.
MCP specification · the 2026-07-28 release · the tools page of the spec · stdio · Anthropic: introducing advanced tool use (Nov 2025) · Anthropic: code execution with MCP (Nov 2025) · the official Python SDK
3. AGENTS.md and CLAUDE.md
A plain Markdown file the harness pastes into the context at the start of every session. AGENTS.md is the open format (now at the AAIF, used in over 60,000 repositories, read by Codex, Cursor, Copilot, Gemini CLI, Zed and many others); CLAUDE.md is Claude Code's own name.
How each harness finds them
- Codex: one global file from
~/.codex/, then from the git root down to your current folder, at most one file per folder (AGENTS.override.mdbeatsAGENTS.md). Concatenated root first, so closer files win. It stops at 32 KiB in total. - Claude Code:
~/.claude/CLAUDE.md, then the project's CLAUDE.md files. Since version 2.1.277 (September 2026) it reads AGENTS.md when no CLAUDE.md exists; a CLAUDE.md that says@AGENTS.mdimports it explicitly. The docs suggest keeping it under about 200 lines.
What to put in it
Commands (how to run, how to test), conventions (units, time zones, coordinate systems), the mistakes a newcomer makes, and pointers to longer docs. Leave out the whole README, style essays, and anything the code already enforces. Every line is resent on every call, and fifty rules dilute each other, so add a line when the agent makes the same mistake twice, and prune it like code. And remember that a line is a request: "never delete data/raw" is followed most of the time. For rules that must hold, use a hook or the sandbox (sections 7 and 9).
agents.md · Codex: AGENTS.md · Claude Code: memory and CLAUDE.md
4. Memory
| Who writes it | When | What enters the context | |
|---|---|---|---|
| AGENTS.md | you | before the session | all of it, every session |
| Memory files | the agent | during a session, for later ones | an index always; each note on demand |
| Compaction summary | the harness | when the context is nearly full | replaces the history (week 2) |
In Claude Code, auto-memory is a folder with a short MEMORY.md index, one line per memory, loaded every session,
and one file per note, read only when relevant. The risk is the same as a lab notebook's: notes go stale, and a wrong one
keeps being trusted in every future session. Open the folder now and then and prune it.
5. Skills and progressive disclosure
A skill is a folder with a SKILL.md (YAML frontmatter, then Markdown instructions) plus anything else: scripts,
references, assets. Anthropic introduced skills in October 2025 and published the format as an open standard in December 2025;
over 40 products read it, including Claude Code, Codex and ChatGPT, GitHub Copilot, Cursor and Gemini CLI.
name: required, 1–64 characters, lowercase letters, digits and hyphens, the same as the folder name.description: required, up to 1,024 characters: what it does and when to use it. It is the only part the agent sees until it decides to use the skill.
Installing and sharing skills
Vercel's skills CLI copies skill folders from GitHub into every agent you use:
npx skills find <query>, npx skills add owner/repo --skill name (-a claude-code -a codex to pick agents,
-g for your user folder), npx skills list, update, remove, and init for a new template.
It knows each agent's folder (.claude/skills/ for Claude Code; .agents/skills/ for Codex, Cursor and others) and supports about 80 agents.
Browse at skills.sh. A skill's scripts run on your computer, so read one before installing it; the CLI sends anonymous usage data unless DISABLE_TELEMETRY=1.
Three levels
| Level | What | When it enters the context | Budget |
|---|---|---|---|
| 1 | name + description | always | about 100 tokens per skill |
| 2 | the SKILL.md body | when the task matches | under about 5,000 tokens (500 lines) |
| 3 | references and scripts | when the body points there | effectively unlimited; scripts run without their code entering the context |
You have already used two: the homework pages (class.xhelio.ai/week-2/homework.md) are short skills that point your agent
to a longer one in the homework repository, .agents/skills/build-a-harness/SKILL.md. That is level 1 → 2 → 3 across a web page and a git clone.
The same idea everywhere
| 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 | a short report | (the work stays in the subagent) |
Keep a short index in the context and the library on disk. The failure mode is a vague index entry: the agent never opens the right chapter.
Anthropic: equipping agents with Agent Skills (Oct 2025) · the Agent Skills specification
6. Plugins, marketplaces and channels
A plugin bundles MCP servers, skills, hooks and subagents in one folder. In Claude Code's layout:
telegram/
├── .claude-plugin/plugin.json # name (required), version, description, author
├── .mcp.json # MCP servers to start; ${CLAUDE_PLUGIN_ROOT} = this folder
├── server.py
├── skills/telegram/SKILL.md
├── hooks/hooks.json # optional
└── agents/ # optional: subagent definitions
- Try one while building:
claude --plugin-dir ./telegram; check it withclaude plugin validate ./telegram. - A marketplace is a git repository with
.claude-plugin/marketplace.jsonlisting plugins:/plugin marketplace add owner/repo, then/plugin install name@marketplace. - Codex has plugins too (since March 2026), shared with ChatGPT; they bundle skills, MCP servers and hooks.
- An enabled plugin costs context on every turn through its skill and subagent descriptions, so enable what you use.
Agent Plugins 1.0: the vendor-neutral format
Agent Plugins (spec published July 2026, launched August 6, 2026) packages the two things all agents agree on:
a plugin.json at the folder root (only $schema and name required), skills/ in the Agent Skills format, and
mcp.json for MCP servers. Agent-specific extras go in reverse-domain folders that other agents ignore. Its steering committee has members from
Amazon, Cursor, Microsoft, OpenAI and Vercel; launch clients were ChatGPT and Codex, Cursor, GitHub Copilot, Kiro and VS Code, with OpenClaw, OpenHands and others since.
Claude Code is not a supported client; it keeps its own format above (.claude-plugin/plugin.json, .mcp.json, plus commands, subagents and hooks).
The skills and MCP servers inside are the same files in both formats; only the manifest differs.
Agent Plugins 1.0.0 specification
Channels: Claude Code's Telegram bridge
A channel is an MCP server that pushes events into a running Claude Code session, so you can message it from your phone.
Anthropic's Telegram, Discord and iMessage channels (research preview) are plugins in the claude-plugins-official marketplace:
/plugin install telegram@claude-plugins-official, then claude --channels plugin:telegram@claude-plugins-official.
It pairs your Telegram account with a code and then drops every other sender: an allowlist.
Its source is public, and worth reading after you have written your own for the homework.
Claude Code: plugins · plugin reference · channels · Codex: plugins
6b. The protocol landscape
| Protocol | Connects | From · status |
|---|---|---|
| MCP | agent ↔ tools and data | Anthropic → Agentic AI Foundation |
| MHS, Model Hardware Standard | agent ↔ physical devices, through a standard driver | Anthropic with HHMI Janelia · research preview since Aug 27, 2026; open source planned |
| ACP, Agent Client Protocol | code editor ↔ coding agent (JSON-RPC over stdio) | Zed and JetBrains · since Aug 2025; 13 editors, 47 agents |
| A2A | agent ↔ agent (week 4) | Google → Agentic AI Foundation · v1.0 |
| AG-UI | agent ↔ the app a person uses (an event stream) | CopilotKit, with LangChain and CrewAI · 2025 |
| Agentic Commerce Protocol | buyer's agent ↔ merchant checkout | OpenAI and Stripe · Sept 2025 |
| UCP and AP2 | agents ↔ shops; signed payment mandates | Google (AP2 now at the FIDO Alliance) |
| MCP Apps | MCP server ↔ an interactive UI in the host | MCP extension, Jan 2026 |
MHS: agents and instruments
"A shared specification for AI agents to safely operate physical devices." An MHS driver translates between an agent and a device with read and write operations (get temperature, set temperature) and a device description, written from plain-language notes, of "what it can measure, what can be adjusted, and what safety limits will be enforced". It is not built on MCP: agents reach the driver through MCP, the command line, or code. Device-level limits, such as a laser power cap, are enforced by the driver, outside the model. Partner-reported: at QuEra an agent relocked a laser in 99.3% of 700 trials, against 58% for hand-written scripts. Labs can apply to the preview at modelhardwarestandard.com.
ACP: any agent in any editor
The editor starts the agent as a subprocess and talks JSON-RPC over stdio: initialize, session/new, session/prompt; the agent
streams session/update notifications, asks session/request_permission, and reads and writes files through the editor
(fs/read_text_file, fs/write_text_file). Claude, Codex, Gemini CLI, Copilot and dozens more have adapters.
Three different protocols are called ACP: this one, the Agentic Commerce Protocol, and IBM's Agent Communication Protocol, which merged into A2A in 2025.
7. Permissions and sandboxes
Permission rules
{ "permissions": {
"allow": ["Read", "Bash(uv run pytest:*)", "Bash(git status)"],
"ask": ["Bash(git push:*)"],
"deny": ["Read(./.env)", "Edit(./data/raw/**)"]
} }
Deny wins over ask, ask over allow. Rules match named tools, so Edit(./data/raw/**) does not stop rm in bash. That gap is what sandboxes and hooks are for.
| Claude Code mode | Behavior |
|---|---|
manual (was default) | ask before edits and commands |
acceptEdits | edits allowed; ask for commands |
plan | read and plan only |
auto | a classifier model reviews each action instead of you; the starting mode since version 2.1.283 |
dontAsk | deny anything that would prompt; for scripts and CI |
bypassPermissions | no checks; only in a container or VM |
Sandboxes
The operating system limits every process the agent starts: Seatbelt on macOS, bubblewrap plus seccomp on Linux. It doesn't matter how clever the command is. Codex sandboxes by default:
| Codex | Options |
|---|---|
| Sandbox | read-only, workspace-write (write in the project only), danger-full-access |
| Approval policy | on-request, never, granular; optionally an automatic reviewer model |
| Default | workspace-write + on-request in a git repository; read-only elsewhere |
Permission prompts make you the check, and tired people approve everything. A sandbox fences once: inside it the agent works freely, and you are asked only when it wants out. Anthropic measured 84% fewer prompts once Claude Code's sandbox was on.
Claude Code: permissions · permission modes · Codex: approvals and security · Anthropic: beyond permission prompts (Oct 2025)
8. Prompt injection
A tool result is more tokens in the same stream as your instructions, and the model cannot reliably tell them apart. Text hidden in a web page, a PDF or a GitHub issue can give your agent orders.
- May 2025: a malicious public GitHub issue made agents using the official GitHub MCP server leak private-repository data into a public pull request (Invariant Labs).
- April 2026: OX Security reported 14 CVEs across 17 AI tools from MCP server configurations: a stdio server entry is a command your computer runs. Install MCP servers and plugins the way you install software, from sources you trust.
The lethal trifecta
Simon Willison: "If your agent combines these three features, an attacker can easily trick it into accessing your private data and sending it to that attacker." The three are access to private data, exposure to untrusted content, and the ability to communicate externally. 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).
Your homework bot has all three: your files, messages from the internet, and a way to send replies. That is why it must accept only your own chat ID, and why you approve each command.
Simon Willison: the lethal trifecta · Invariant Labs: GitHub MCP exploited · OX Security: MCP supply-chain advisory
9. Hooks
A hook is a script the harness runs at a fixed point in the loop. It gets the event as JSON on stdin. Exit code 2 blocks the action and
sends what it printed to stderr back to the model; a hook can also print JSON with permissionDecision: allow, deny or ask.
| Event | Fires | Typical use |
|---|---|---|
SessionStart | when a session starts | load today's context |
UserPromptSubmit | before your prompt goes to the model | add or check context |
PreToolUse | before every tool call | allow, block or ask |
PostToolUse | after every tool call | format, lint, check the result |
Stop | when the agent wants to finish | run the tests; keep it working if they fail |
Claude Code has over thirty events (also for subagents, compaction, permission requests and more). Codex added hooks in 2026, with a dozen
events and the same shape; non-managed hooks must be reviewed with /hooks before they run.
// .claude/settings.json: block edits to raw data, and run the tests before "done"
{ "hooks": {
"PreToolUse": [{ "matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": ".claude/hooks/protect-raw.sh" }] }],
"Stop": [{ "hooks": [{ "type": "command", "command": "uv run pytest -q 1>&2 || exit 2" }] }]
} }
10. Subagents (next week's topic)
To the main agent, a subagent is one tool call. Inside, it is a whole new loop with a fresh context, its own tools and maybe a cheaper model;
only its final report comes back. Claude Code defines them as Markdown files in .claude/agents/ (frontmatter: name,
description, optional tools, model, …; the body is the system prompt). Codex uses TOML files in
.codex/agents/ with name, description and developer_instructions.
Claude Code: subagents · Codex: subagents · Anthropic: how we built our multi-agent research system
11. If you read only three things
- Model Context Protocol: introductionThen the Python SDK's README, which you need for the homework.
- Anthropic: equipping agents with Agent SkillsProgressive disclosure, explained by the people who designed skills.
- Simon Willison: the lethal trifecta for AI agentsRead before you connect your agent to Telegram.