Agent identity: session tokens, Bearer-only API, honest history attribution

[HamptonMakes]

The bug

Agent edits made in production showed on the history tab as edits the human made themselves. Two compounding causes:

1. Write side — in production the proxy authenticates curl automatically (the API config even says so), so a local agent's requests arrive on the user's credentials with no Bearer token. api_author_type derived actor type from the auth mechanism (token → local_agent, hook → human), so every agent edit was persisted as actor_type: "human" with the user's id.
2. Read side — the history partials rendered avatar + name whenever actor_id resolved to a user, and only showed the actor-type badge in the else branch. Even a correctly-typed agent version rendered as the plain human.

The fix: every API caller has a real identity

Session tokens (POST /api/v1/tokens): each agent run mints its own short-lived token (default 12h, cap 7d) carrying an agent_name — either as a child of a long-lived root token from the settings UI (revoking the root revokes everything it minted; children can't mint, so the tree stays one level deep), or bootstrapped directly from the host's request auth for zero-setup production use. DELETE /api/v1/tokens/current lets a run revoke itself on exit instead of leaving a live credential until the TTL.

Bearer-only API: every other /api/v1 call now requires the token, with a 403 that tells the caller exactly how to mint. Hook auth proves which human is behind the wire, never which agent is acting — so it's accepted for exactly one thing: minting.

Attribution matching comments: coplan_plan_versions and coplan_plan_events gain agent_name; API writes store the human in actor_id (never the token id — a token id names nobody in a history tab) and the acting agent in agent_name, resolved per-request → token's agent_name → token's name. The history tab renders "Claude (via Hampton)", exactly the convention comment authors already use. The expired-session auto-commit job resolves identity the same way. API comments now fall back to the token's agent name instead of 422ing when agent_name is omitted.

Token metadata + provenance join (second commit): identity is more than a display name — harness, harness version, model. Rather than growing columns on three tables, minting accepts a schemaless metadata JSON object ({"harness": "claude-code", "harness_version": "2.1.3", "model": "claude-fable-5"} — keys are convention, like a User-Agent; 4 KB cap; non-hash input coerced to {} so a malformed field never costs an agent its identity), and every version, event, and comment records api_token_id (indexed, FK'd) pointing back at the token that wrote it. The history UI stays one string; anything richer joins through the token. No UI surfacing yet — that's deliberate; a tooltip/detail view can come later without touching the data model.

The agent instructions document the mint-first flow (they're re-read every session, so agents adopt it automatically), including the metadata param.

Notes

• The api_tokens migration is guarded with column_exists?: main's db/schema.rb has carried these columns — plus the unreleased agent-collaboration tables — without backing migrations since the schema regeneration in Voice commenting: push-to-talk dictation pinned to what you were reading #175. Schema-loaded databases already have the columns; production's migrated database doesn't. The stray coplan_agent_sessions/coplan_agent_events tables in schema.rb are left for the agent-collaboration PR that owns them.
• Existing production rows written as "human" can't be re-attributed — nothing distinguishes them. The fix is forward-looking.
• After the engine bump, coplan-square's agent_auth_instructions ("Authentication is automatic with curl") should be reworded to describe the mint-first flow — I'll include that in the bump PR.

Testing

• Full suite: 1447 examples, 0 real failures (one transient chromedriver fetch, green on rerun).
• New coverage: minting (child, bootstrap, TTL clamp, no grandchildren, cascade revoke, expired-parent), Bearer enforcement (hook-auth reads/writes 403 with mint pointer), attribution on content PUT / session commit / attachment events (actor_id = user, agent_name = token), and a history-page system spec asserting "Claude (via …)".
• Metadata/provenance coverage: mint persists + echoes metadata, non-hash coerced to {}, over-budget 422, api_token_id recorded on versions and comments. Models + services + API + jobs: 937 examples, 0 failures.

🤖 Generated with Claude Code

Update — 2026-08-17

• Rebased onto current main and resolved the schema-version conflict while preserving the newer schema.
• Fixed review feedback so API-created plans attribute version 1 to the agent and retain the originating token provenance.
• Verification: full suite, 1,485 examples, 0 failures; targeted RuboCop, 4 files, no offenses.

Update — 2026-08-17 (attribution audit)

• Closed the remaining attribution gaps: API comment deletions and library/folder audit events now persist agent name and API-token provenance.
• Added direct Active Record provenance associations and exposed agent identity on library-event API responses.
• Verification: full suite, 1,485 examples, 0 failures; focused attribution suite, 59 examples, 0 failures; RuboCop, 15 files, no offenses.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 91bcb32255

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Propagate agent identity into the initial plan version

When a Bearer-authenticated agent calls POST /api/v1/plans, PlansController#create still invokes Plans::Create with only user, and that service hardcodes version 1 as actor_type: "human" without an agent_name. Consequently, every agent-created plan permanently attributes its initial content to the human, contradicting the new identity model and the documented promise that every version is stamped; pass api_author_type, api_user_id, and api_agent_name through the creation path as well.

AGENTS.md reference: AGENTS.md:L5-L5

Useful? React with 👍 / 👎.

[HamptonMakes]

Fixed: API plan creation now passes the actor type, user ID, agent name, and API token ID into Plans::Create, so the initial version is attributed to the agent instead of the human. Added request and service regression coverage.