feat(shapes): built-in ACP, model-direct and command-template solutions

[Ruqii]

Summary

Three built-in solutions ("shapes") that a hand-written trap.yaml can use as its cmd:, so an agent product, a bare model, or someone else's program can be tested without a wrapper repo and without glue code:

Shape	What it runs	Example cmd:
tp shape acp	any ACP agent (verified: claude-acp, codex-acp)	tp shape acp --agent-cmd "npx -y @agentclientprotocol/claude-agent-acp@0.76.0" --agent-id claude-acp --model sonnet
tp shape direct	one non-streamed call to a model API (Anthropic or OpenAI-compatible)	tp shape direct --model claude-sonnet-5
tp shape cmd	a one-line command template around someone else's program	tp shape cmd --repo . --template "python {repo}/main.py --question {prompt}"

Each shape is an ordinary solution under the existing IO contract: the runner starts it as the solution subprocess, it reads TRAP_MANIFEST, prints the answer on stdout and exits with a fixed code. The runner, judge, grader, report.json and live sync are untouched, and the existing cost proxy meters the shapes like any other solution. tp shape is a hidden sub-app.

This is phase 1 of the solution-registry work: the building blocks only. The zero-config front end (tp run --agent claude-acp --model sonnet, a card recorded in the run's provenance, first-case confirmation) comes next, built on these interfaces.

What every shape guarantees

• Fresh work directory per case: mkdtemp(prefix="trap-case-"), mode 0700, holding a copy of that case's inputs only. It is never under the task checkout or .trap/, and it is removed afterwards.

• No links into the answers: a case whose inputs contain a symlink anywhere is refused with 24, and so is an acp --skill directory that contains one. A link could point at expected/, so the copy never creates or follows one. What trap cannot tell apart from ordinary files is documented as the task author's responsibility:

  • a hard link to an answer;
  • a copy of an answer.

• The runner refuses a task that would hand a solution its answers (new, applies to every solution). tp run exits 2 before any case runs, and before any prompt or site traffic, if any of these holds:

  • something from the inputs root down to or inside a running case's inputs is a symlink;
  • an answers directory, meaning the expected root or any case's expected dir, lies inside a running case's inputs;
  • a case's answers directory is, or lies around, a case's directory;
  • a case id has a . or .. segment.

  Answers directories are resolved through links and compared by (st_dev, st_ino), so macOS case, Unicode and firmlink spellings count. The built-in shapes check again for hand-made manifests. The manifest and the IO contract are unchanged.

• No answer leaks through the environment: the child never gets TRAP_MANIFEST, the task's manifest variable, or any variable naming the inputs root or a --scrub path. PATH HOME TMPDIR LANG SHELL TERM USER LOGNAME are never dropped. (This stops accidental discovery, not a determined same-user agent; the guide says so.)

• No orphans: the child runs in its own process group. At --deadline (default 570 s, under trap.yaml's default 600 s timeout) the shape cancels (ACP session/cancel), then kills the whole group. SIGINT/SIGTERM do the same before the shape exits with 128+signal.

• One exit-code table, the same for all three shapes: 0 answer · 20 refusal · 21 max_tokens · 22 max_turn_requests · 23 agent error (crash, protocol error, auth failure, a reply that is not an answer) · 24 config error (bad args, model/option not offered, unsupported input, command not found) · 124 deadline. Every failure prints one [trap] line on stderr, never a traceback. tests/test_shapes_backstop.py feeds garbage at every boundary to hold this.

ACP details (from a live probe on 2026-09-12)

• initialize with protocolVersion: 1 and no fs/terminal capabilities. session/new gets an absolute cwd and mcpServers: [].
• --model must exactly match a value the agent lists for its category == "model" option. For claude-acp these are aliases (sonnet, haiku, opus[1m] …), and the running values of all options are logged.
• claude-acp isolation: _meta.claudeCode.options.settingSources = ["project"], so only the temp dir's .claude/ loads, not the runner's CLAUDE.md, skills, hooks or plugins. --skill <dir> installs into that .claude/skills/.
• codex-acp: CODEX_CONFIG redirects to the cost proxy only under an API-key login. Under a ChatGPT login the redirect 401s, so the run goes unmetered instead.
• Permissions: allow_once, else reject_once, else cancelled — never allow_always.
• The answer is the agent's last message, split by messageId, not every chunk joined. A turn only counts as an answer if the agent did not report zero model use. The probe saw codex answer a 401 with end_turn and the error text as its message. Earlier messages and tool calls go to the case's stderr, which stays local.

Model-direct details

• One non-streamed call. Anthropic gets max_tokens = 16000; OpenAI-compatible providers get no output cap. Thinking and effort stay at API defaults and are logged.
• The request goes to <PROVIDER>_BASE_URL, so under tp run it passes through the cost proxy and is metered. This is tested end to end against a loopback vendor.
• A case with any input file besides the prompt file is refused with 24, since model-direct sends the question only.

Changes outside src/trap/shapes/

• src/trap/cost/providers.py: a public provider_config(name), appended.
• src/trap/runner/leaks.py holds the answer-leak check. src/trap/runner/layout.py gains task_root, which the runner and the check share so both resolve the same roots. src/trap/errors.py holds ConfigError, moved to a leaf module and re-exported from trap.loader.errors. src/trap/cli/__init__.py runs the check first and escapes config-error text for Rich.
• src/trap/cli/__init__.py: the hidden shape sub-app, which passes its arguments straight through, and pretty_exceptions_show_locals=False.
• tests/conftest.py: case_capture, process_gone, and signal_handlers_unchanged helpers.
• Docs:
  • new guide docs/guides/built-in-shapes.md;
  • ## tp shape in docs/reference/cli.md;
  • a pointer in writing-solution.md;
  • docs/manifest.json;
  • CODE_MAP.md edges cli --> shapes, shapes --> cost.

No new runtime dependencies: JSON-RPC over stdio is hand-written, and httpx was already declared.

Tests

• Hermetic: a scripted fake ACP agent (tests/fake_acp_agent.py) and loopback HTTP vendors. No npx, no network, and nothing depends on the developer's ~/.codex, ~/.claude or API keys.
• Gates, run locally: ruff check, ruff format --check, lint_docs.py, pyright src/ (0 errors), and pytest --cov — 1167 passed, 15 skipped at 100.00% branch coverage.

Not yet done

• One live claude-acp case under tp run (about $0.05), to confirm answer, cost and cleanup against the real agent.
• The claude-acp subscription path (the local login had expired at probe time) and codex's API-key metering path are still unverified.

🤖 Generated with Claude Code