feat(subagents): artifact_read + workspace staging, artifact counts, docs (M2+M3)

[jkyberneees]

Part of the SUBAGENT_RESULT_ARTIFACTS_PLAN.md workstream. M1 shipped in #159 (v1.32.0); this PR completes the plan: M2 content access + M3 staging/relocation, events, docs.

M2 — artifact_read (parent-only content access)

Artifacts larger than the 32 KiB inline budget were metadata-only after M1. Now the parent reads full content on demand, by id:

artifact report (text/markdown, 18432 bytes, sha256:ab12cd34ef56) — bytes 0..65536 — TRUNCATED, call again with offset to continue

• Session-scoped registry: delegate_tasks registers every ref that passed fail-closed validation at collation, with the validated path. 512 live entries, oldest-first eviction with lazy slots (a last-wins re-registration can never evict a live entry).
• No model input reaches the filesystem as a path — the model supplies only the id; resolution is internal. Traversal-shaped ids are simply unknown.
• Re-verified at read time (janitor/cleanup may have removed the subtree) · default 64 KiB per call, 256 KiB hard cap, offset paging with explicit TRUNCATED flag · content inside wrapUntrusted, recorded by the per-call audit ingest.
• Parent-only: gated on SelfTrust == "" in builtinTools.
• Duplicate ids across tasks: last-wins + explicit note line.

M3 — staging + relocation, events, docs

The gap M1 left: children could not actually deliver artifacts — ~/.odek/artifacts is doubly protected from child writes (confineToCWD rejects absolute paths; the classifier escalates ~/.odek writes to system_write, denied for approval-less children). M3 resolves it without touching either gate:

• Children stage deliverables inside the workspace (.odek-artifacts/<task_id>/ — an ordinary local_write), pointed there by a trusted runner note (workspace-relative path only).
• The trusted child runner relocates them to the canonical dir before the exit scan (rename, cross-device copy fallback), then hashes/sizes there. Wire format unchanged (artifact_root still names the canonical dir — v1.32.0 compatible).
• subagent_completed events carry artifact_count (count only — hash-only event policy preserved).
• Docs in the same change: CONFIG.md + MAINTENANCE.md (maintenance.artifacts_max_age_hours, ODEK_MAINTENANCE_ARTIFACTS_MAX_AGE_HOURS, explicit 0 = keep forever), SECURITY.md (artifact invariants), SUBAGENTS.md (Result artifacts section), EXTENSIONS.md (sub-agent reuse of odek.artifact-ref/v1).

Also carries the CI fixes from review: maintenance.artifacts_max_age_hours properly wired (config field + overlay + env + want-literals) and runTask's empty-result error now carries waitErr/scannerErr for diagnosability.

Verification

• RED first: artifact_read_test.go (9 tests: registry mechanics incl. eviction/last-wins, no-path-leak, untrusted wrap, paging/clamping, unknown-id listing, traversal id, vanished file, parent-only gate, duplicate notes) and subagent_staging_test.go (staging path, relocation + staging removal, copy fallback, no-op, event count, no canonical-path leak).
• Full cmd/odek suite: ok (darwin 73s · linux container 62s) · -race scoped: ok · golangci-lint: 0 issues

Plan status

With this, the SUBAGENT_RESULT_ARTIFACTS_PLAN.md milestones are complete (M0/M1 in #159+v1.32.0, M2/M3 here).

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	odek	cc5b3c3	Commit Preview URL Branch Preview URL	Aug 30 2026, 03:46 PM