Agent Harness Engineering Demos

Four local, safe Claude Code demos for teaching the core idea behind harness engineering:

Prompt is advice. Mechanism is policy.

The demos use a fake email assistant to show how an agent can be given brakes, narrower tools, least privilege, and auditability. Everything runs locally with mock data. No real email, customer data, network request, payment, or production system is touched.

Demo Folders

Folder	Topic	Mechanism
claude_code_demo1/	Human approval	PreToolUse hook asks before send_email.py runs
claude_code_demo2/	Permission gate	PreToolUse hook denies raw dangerous shell commands and routes risky actions through narrow tools
claude_code_demo3_account_permission/	Least privilege	No hook; OS-style file permission and account scope block data exfiltration
claude_code_demo4_observability/	Audit replay	PostToolUse hook appends every action to output/audit_log.jsonl

The four demos are intentionally separate folders so they can be taught one at a time or copied into a public GitHub repo later.

Quick Start

Use Python 3. No third-party packages are required.

git clone git@github.com:thegiive/harness_engineering.git
cd harness_engineering

Smoke-test the scripts:

python3 -m py_compile \
  claude_code_demo1/.claude/hooks/approve_send.py \
  claude_code_demo1/tools/send_email.py \
  claude_code_demo2/.claude/hooks/permission_gate.py \
  claude_code_demo2/tools/*.py \
  claude_code_demo3_account_permission/tools/*.py \
  claude_code_demo4_observability/.claude/hooks/audit_log.py \
  claude_code_demo4_observability/tools/*.py \
  claude_code_demo4_observability/replay.py

Open each folder in Claude Code to run the real hook demo:

cd claude_code_demo1
claude

Claude Code will ask whether you trust the project hooks. Trust only when you are intentionally running the demo.

What To Teach

Demo 1 shows that "do not send email" should not live only in a prompt. The hook sees send_email.py, returns permissionDecision: "ask", and forces human approval.

Demo 2 shows that tools should be narrow and typed. Raw shell shortcuts such as curl, mail, sudo, and rm are denied. Registered L1/L2 tools are allowed. Registered L3/L4 tools ask for approval.

Demo 3 shows the hardest layer: system and account permission. Even with no hook, the agent cannot read the protected vault or send with a token that lacks email.send.

Demo 4 shows auditability. It does not block; it records every tool call after execution and lets you replay the timeline.

Demo 3 Setup

Demo 3 intentionally depends on local file permissions. Run this before teaching it:

cd claude_code_demo3_account_permission
./setup.sh
python3 tools/read_vault.py
python3 tools/send_email.py --id email-004 --to mallory@unknown.example

You should see Permission denied for the vault read and 403 Forbidden for sending. After the class, run ./reset.sh if you want to edit or delete the vault file.

Public GitHub Notes

This directory is prepared to become a public repo:

• .gitignore excludes local settings, generated output, caches, and OS metadata.
• LICENSE is included.
• PUBLICATION_CHECKLIST.md lists the final checks before publishing.
• All sample data is fake and uses example domains.

Before publishing, run the checklist and make sure no course-private files were copied into this folder.