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
  2. MCP
  3. AGENTS.md and CLAUDE.md
  4. Memory
  5. Skills and progressive disclosure
  6. Plugins, marketplaces and channels
  7. The protocol landscape
  8. Permissions and sandboxes
  9. Prompt injection
  10. Hooks
  11. Subagents
  12. Sources

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:

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

KindRunsExamples
Client toolin your harness, on your computerbash, read a file; your loop sees every call and can refuse it
Server toolat the model provider, inside the same API callOpenAI's web_search; Anthropic's web search and code execution
MCP toolin a separate program, local or remoteany 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

PrimitiveWhat it isWho decides to use it
Toolsfunctions the model can callthe model
Resourcesdata the app attaches to the context: a file, a tablethe application
Promptsreusable templates, often shown as slash commandsthe 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

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:

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

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 itWhenWhat enters the context
AGENTS.mdyoubefore the sessionall of it, every session
Memory filesthe agentduring a session, for later onesan index always; each note on demand
Compaction summarythe harnesswhen the context is nearly fullreplaces 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.

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

LevelWhatWhen it enters the contextBudget
1name + descriptionalwaysabout 100 tokens per skill
2the SKILL.md bodywhen the task matchesunder about 5,000 tokens (500 lines)
3references and scriptswhen the body points thereeffectively 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

WhereAlways in contextLoaded on demand
Skillsname + descriptionbody, references, script output
Tool searchtool namesa tool's full schema
AGENTS.mdthe short filethe docs it points to
Memorythe indexeach note
Subagentsa 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

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

ProtocolConnectsFrom · status
MCPagent ↔ tools and dataAnthropic → Agentic AI Foundation
MHS, Model Hardware Standardagent ↔ physical devices, through a standard driverAnthropic with HHMI Janelia · research preview since Aug 27, 2026; open source planned
ACP, Agent Client Protocolcode editor ↔ coding agent (JSON-RPC over stdio)Zed and JetBrains · since Aug 2025; 13 editors, 47 agents
A2Aagent ↔ agent (week 4)Google → Agentic AI Foundation · v1.0
AG-UIagent ↔ the app a person uses (an event stream)CopilotKit, with LangChain and CrewAI · 2025
Agentic Commerce Protocolbuyer's agent ↔ merchant checkoutOpenAI and Stripe · Sept 2025
UCP and AP2agents ↔ shops; signed payment mandatesGoogle (AP2 now at the FIDO Alliance)
MCP AppsMCP server ↔ an interactive UI in the hostMCP 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 modeBehavior
manual (was default)ask before edits and commands
acceptEditsedits allowed; ask for commands
planread and plan only
autoa classifier model reviews each action instead of you; the starting mode since version 2.1.283
dontAskdeny anything that would prompt; for scripts and CI
bypassPermissionsno 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:

CodexOptions
Sandboxread-only, workspace-write (write in the project only), danger-full-access
Approval policyon-request, never, granular; optionally an automatic reviewer model
Defaultworkspace-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.

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.

EventFiresTypical use
SessionStartwhen a session startsload today's context
UserPromptSubmitbefore your prompt goes to the modeladd or check context
PreToolUsebefore every tool callallow, block or ask
PostToolUseafter every tool callformat, lint, check the result
Stopwhen the agent wants to finishrun 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" }] }]
} }

Claude Code: hooks · Codex: hooks

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