Add opaque LLM agent SHA attribution for issues, branches, PRs, and review handoffs #86
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
We need a safe way for each LLM/session/agent to identify its own work across issues, branches, PRs, and review handoffs without exposing an obvious human/model identity.
Current problem
The review/merge safety gate correctly uses the authenticated Gitea user/profile, not the LLM session identity. This must remain true. However, multiple LLM sessions may all authenticate through the same Gitea author account, usually
jcwalker3, when creating implementation PRs. Later, another LLM session may be asked to review, but if its MCP server is still authenticated asjcwalker3 / gitea-default, it is blocked as the PR author. The LLM may also be confused because it did not personally write the code, even though Gitea sees it as the same authenticated author.We need attribution that separates:
Important safety rule
LLM agent identity must not replace the authenticated Gitea user/profile gates. Self-review/self-merge protections must still be enforced by Gitea authenticated user and MCP profile permissions. LLM agent identity is for attribution, routing, audit clarity, and operator workflow only.
Proposed identity format
Use an opaque SHA-like identifier instead of a friendly or obvious name.
Examples:
The value should:
Suggested generation
Generate a random or hash-derived short identifier such as:
Examples:
Do not derive it from:
Suggested PR body metadata block
Suggested review metadata block
Acceptance criteria
LLM-Agent-SHA.allowed_operationsNon-goals
prgs-reviewer/gitea-defaultprofile separation.Open questions
LLM_AGENT_SHAandLLM_AGENT_ROLE?gitea_whoamiinclude both Gitea identity and LLM agent SHA?LLM-Agent-SHAon all mutating actions?Discussion: Proposed
LLM-Agent-SHADecision and Implementation ShapeThis is LLM feedback for discussion only. It is not yet the final owner decision.
1. Recommended Direction
Adopt
LLM-Agent-SHAas informational/audit metadata only.It is useful for tracing multi-agent work, debugging handoffs, and understanding which LLM session produced or reviewed a given artifact. However, it must never be used for authorization, review eligibility, merge eligibility, or profile permissions.
The security boundary remains:
allowed_operationsIf two different LLM sessions have different
LLM-Agent-SHAvalues but authenticate as the same Gitea user, the safety gates must treat them as the same actor.2. Proposed Near-Term Implementation
Possible implementation shape:
LLM-Agent-SHAmetadata value.Possible visibility options:
or a less visible HTML comment:
3. Security Requirement
Add an explicit negative test proving that
LLM-Agent-SHAdoes not affect authorization.Required test scenario:
This test must prove that a different SHA does not bypass the Gitea authenticated-user safety gate.
4. Deferred Items
Defer:
These can wait until the broader MCP Control Plane architecture is clearer.
5. Risks
False sense of security
Operators or LLMs may mistakenly think different SHAs mean separate review identities.
Mitigation:
Documentation and tests must state clearly that only Gitea user/profile controls eligibility.
UI clutter
Adding SHA metadata to every issue/comment/PR may clutter Gitea.
Mitigation:
Use a small handoff block only where useful, or HTML comments for low-visibility attribution.
Spoofing
If an LLM self-generates the SHA, it can be changed or spoofed.
Mitigation:
Accept this for phase 0 because SHA is informational only. Longer term, prefer launcher-injected SHA.
6. Questions for Owner Decision
Before implementation, decide:
gitea_whoamireturnLLM-Agent-SHAandLLM-Agent-Role?7. Current Recommendation
Recommended phased approach:
llm-<12 hex>in handoff metadata.LLM_AGENT_SHAandLLM_AGENT_ROLE.gitea_whoami, audit logs, and PR creation include the metadata automatically.LLM-Agent-SHAfor review/merge eligibility.Owner Decision: Phase 0
LLM-Agent-SHAAttributionApproved direction:
LLM-Agent-SHAis informational attribution metadata only.It must never be used for authentication, authorization, review eligibility, merge eligibility, profile permissions, or any other security decision.
The security gates remain:
allowed_operationsDifferent
LLM-Agent-SHAvalues under the same authenticated Gitea user are still the same actor for review/merge safety.Phase 0 — Approved Now
Implement Phase 0 only:
Document the
LLM-Agent-SHAconvention.Use format:
Recommended validation:
SHA lifetime:
A per-session SHA is acceptable if it maps cleanly to one workstream.
The SHA should be included in handoff metadata blocks, for example:
Review handoffs should include:
Add or update documentation so LLMs and operators clearly distinguish:
LLM-Agent-SHAAdd explicit negative tests proving:
The tests must prove that
LLM-Agent-SHAis never consulted by the eligibility logic.Visibility Decision
Use visible markdown metadata blocks for Phase 0.
Do not use hidden HTML comments yet. Hidden comments may be reconsidered later if UI clutter becomes a problem.
Branch/Worktree Decision
Do not put
LLM-Agent-SHAin branch names or worktree names.Branches and worktrees should remain human-readable and issue-based.
Deferred
Do not implement these in Phase 0:
LLM_AGENT_SHA/LLM_AGENT_ROLEenvironment injectiongitea_whoamireturning SHA/roleThese may become follow-up phases after Phase 0 lands.
Never Allowed
The SHA must never:
allowed_operationsImplementation Scope for #86
For this issue, implement Phase 0 only unless a follow-up owner decision expands scope.
Expected scope:
No launcher work, no audit schema changes, and no automatic PR injection in this phase.