Tau: The Reference Harness to Attack and Harden
Tau is Hugging Face's educational reimplementation of Pi — ~3,000 LOC across three packages, real enough to attack, small enough to read in an afternoon, and undefended against every surface B2-B8 covers. This deep-dive maps tau's seven attack surfaces to the five explicit extension points where each control attaches: tool-executor wrapping (B2/B4), the bash factory (B7), the credential store (B5), event subscription (B8), and tool-list construction (B0/B1). The two-bash-tool finding and the factory-level fix. The hardened session composition.
Tau is the ideal teaching target because it is real (a bash tool that actually runs asyncio.create_subprocess_shell; a credential store that actually holds plaintext API keys on disk), small (~3,000 LOC across three packages, readable in an afternoon), and undefended (none of the controls B2-B8 build exist today — every control you add is a net-new feature, and its absence is the vulnerability you're closing).
Tau has no plugin system — no register_tool, no hook framework, no middleware (verified by grepping the entire source). Every control attaches by wrapping or replacing objects at five explicit, named sites. This is a feature, not a limitation: it makes every wedge point auditable and teachable, and four of the five extension points are pure wrapping or additive (no monkey-patching).
The two-bash-tool finding is the single most important implementation detail for a security engineer: run_terminal_command (session.py:1183) constructs its own bash tool outside the harness list and calls it directly (session.py:1187), bypassing any tool-list-level control. The clean fix is to wedge at the factory level — replace create_bash_tool itself so both call sites receive the sandbox policy. This generalizes: any control wedging at the tool-list layer is bypassable by any code path that constructs its own tool outside the list.
The load-bearing architectural lesson is that enforcement belongs in the tool, not the loop. The loop delegates to tool.execute, which delegates to tool.executor; you wrap the executor (Extension Point 1), and the loop stays untouched. The hardened session composes all five extension points because the surfaces overlap and the controls are coupled (B5 secures credentials at rest but the agent can still cat them without B7; B7 blocks exfiltration but bash still runs injected commands without B2). The scorecard measures the delta, not any individual control.