cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity

docs(spec): seventeenth pass documenting MCP token limitation and curl workaround

Browse Source 
- Added Section 6.17.0: MCP Token Limitation — single server-level token,
  no per-call override, PR Reviewer must use curl for writes
- Rewrote Section 21.22: "Total Bash Lockdown" -> "Restricted Bash with curl"
- Added READ-via-MCP/WRITE-via-curl operation table
- Added v1.32.0 revision entry
This commit is contained in:
clever-agent
2026-04-10 20:37:33 +00:00
parent bdfd4dd042
commit 5dda3a2c43
1 changed files with 32 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/development/agent-system-specification.md
+32 -7
View File
@@ -1166,7 +1166,31 @@ When the Issue Finder queries open issues, it returns them in this priority orde
**Separation of concerns:**
- The **primary account** creates PRs, manages issues, pushes code, applies labels, and merges PRs.
- The **reviewer account** ONLY posts reviews and review-related comments. It does not create PRs, issues, or push code.
- The PR Review Pool Supervisor receives both sets of credentials from the Product Builder and passes the reviewer credentials to each PR Reviewer instance it dispatches.
- The PR Review Pool Supervisor receives both sets of credentials from the Product Builder and passes all three reviewer credentials (`PAT`, `USERNAME`, `PASSWORD`) to each PR Reviewer instance it dispatches.
#### 6.17.0 MCP Token Limitation and the curl Workaround
!!! warning "Critical Implementation Constraint"
The Forgejo MCP tools (e.g., `forgejo_create_pull_review`, `forgejo_create_issue_comment`) authenticate using a single token configured at the MCP server level. **There is no way to override the token on a per-call basis.** This means all MCP tool calls authenticate as the primary bot account, regardless of which agent invokes them.
**Consequence for the PR Reviewer:** The PR Reviewer cannot use `forgejo_create_pull_review` or `forgejo_create_issue_comment` MCP tools — those would create reviews as the primary bot (the PR author), which Forgejo would reject as self-approval. Instead:
- **READ operations** (get PR details, list reviews, get diff, list comments): Use Forgejo MCP tools normally. Reads don't care which account authenticates.
- **WRITE operations** (post formal review, post backup comment): Use `curl` with the `FORGEJO_REVIEWER_PAT` header. This is the ONLY way to authenticate as the reviewer account.
The PR Reviewer's permission block enforces this split:
- `bash: "curl *": allow` — enables curl-based API calls
- `forgejo_create_pull_review: deny` — blocks the MCP tool (would use wrong token)
- `forgejo_create_issue_comment: deny` — blocks the MCP tool (would use wrong token)
| Operation | Tool | Authentication |
|-----------|------|---------------|
| Get PR details | `forgejo_get_pull_request_by_index` (MCP) | Primary bot (fine for reads) |
| List reviews | `forgejo_list_pull_reviews` (MCP) | Primary bot (fine for reads) |
| Post formal review | `curl` with `FORGEJO_REVIEWER_PAT` | Reviewer bot ✓ |
| Post backup comment | `curl` with `FORGEJO_REVIEWER_PAT` | Reviewer bot ✓ |
| Fetch CI logs | `ci-log-fetcher` with reviewer credential overrides | Reviewer bot ✓ |
#### 6.17.1 Three-Tier Approval Detection
@@ -3390,15 +3414,15 @@ The Git Commit Helper wraps git commit operations with validation, conflict reso
**Output**: Returns structured JSON with `commit_sha`, `commit_message`, `files_changed`, and `stats` (insertions, deletions).
### 21.22 PR Reviewer: Total Bash Lockdown
### 21.22 PR Reviewer: Restricted Bash with curl for Reviewer Authentication
The PR Reviewer agent has `bash: "*": deny` — a total bash lockdown that is more restrictive than most agents. Combined with `edit: deny`, this makes the PR Reviewer one of the most constrained agents in the system. It can only:
The PR Reviewer agent has `bash: "*": deny` with a selective exception for `curl *: allow`. Combined with `edit: deny`, this makes the PR Reviewer highly constrained — it can only:
- Read Forgejo data via MCP tools (PRs, issues, comments, reviews, diffs)
- Invoke two subagents: `ref-reader` (for specification context) and `ci-log-fetcher` (for CI failure analysis)
- Post reviews and comments via Forgejo MCP tools
- **Read** Forgejo data via MCP tools (PRs, issues, comments, reviews, diffs) — these authenticate as the primary bot, which is fine for reads
- **Write** reviews and comments via `curl` with `FORGEJO_REVIEWER_PAT` — this authenticates as the reviewer bot, enabling formal APPROVED reviews
- Invoke two subagents: `ref-reader` (for specification context) and `ci-log-fetcher` (for CI failure analysis, with reviewer credential overrides)
It cannot run any bash commands, edit any files, or invoke any other subagents. This extreme lockdown is intentional: the reviewer must provide an independent assessment without the ability to modify code or run tests. Its perspective must be purely analytical.
It cannot edit any files, run arbitrary bash commands, or invoke any other subagents. The `curl` exception exists solely to enable reviewer-authenticated API calls (see Section 6.17.0 for the MCP token limitation). The Forgejo MCP write tools (`forgejo_create_pull_review`, `forgejo_create_issue_comment`) are explicitly denied in its permissions to prevent accidentally using the wrong account.
### 21.23 Branch Setup: Rebase-Only Policy
@@ -3547,6 +3571,7 @@ The Branch Setup agent creates or checks out branches with a strict rebase-only
| 2026-04-10 | 1.21.0 | Twenty-fourth pass (label deny and permission consistency audit): Expanded Section 6.19 from Automation-Tracking-Manager-specific to universal label application delegation rule documenting all 77 agents with deny + 2 intentional exceptions (forgejo-label-manager, issue-state-updater); **fixed 6 agent definition bugs**: pr-editor.md, pr-manager.md, pr-merge-pool-supervisor.md, async-agent-manager.md (all 4 missing `forgejo_add_issue_labels: deny` — could bypass label delegation), forgejo-signature-appender.md (missing deny AND broken YAML `permission: {}` creating disconnected forgejo block); verified 41 edit:deny agents match spec claim exactly, 3 webfetch:allow agents match spec claim exactly |
| 2026-04-10 | 1.22.0 | Twenty-fifth pass (directory layout, bash permissions, subsystem verification): Added Section 2.4 (Directory Layout) documenting `.opencode/` structure including agents/, shared/, config/, scripts/, deprecated stubs; **fixed 1 agent definition bug**: forgejo-signature-appender.md (missing `bash: "*": deny` and `edit: deny` — the only active agent without any bash restriction, could run arbitrary commands despite being a text-formatting-only agent); verified 3-Tier Approval Detection (Section 6.17) matches pr-merge-pool-supervisor implementation; verified Mandatory Merge Verification Protocol (Section 8.3.4) matches shared/merge_safety.md; confirmed zero remaining stale names, stale labels, or stale session prefixes across all agent files |
| 2026-04-10 | 1.23.0 | Twenty-sixth pass (deep automation tracking audit): Major rewrite of Section 5.2 (Status Issues) with one-at-a-time invariant, close-ALL-then-create protocol, and explicit "even from previous sessions" language; new Section 5.3.1 (Announcement Issue Lifecycle) with mandatory self-review every 3 cycles; new Section 5.3.2 (Tracking Issue Consumption Protocol) with per-agent triage table, read depth levels, and priority-based filtering; **fixed 4 agent definitions**: automation-tracking-manager.md (strengthened CREATE_TRACKING_ISSUE to specify close-ALL-then-create invariant), backlog-grooming-pool-supervisor.md (added READ_ANNOUNCEMENTS from watchdog/liaison/owner + REVIEW_OWN_ANNOUNCEMENTS every 3 cycles), pr-review-pool-supervisor.md (added READ_ANNOUNCEMENTS for critical watchdog/liaison + REVIEW_OWN_ANNOUNCEMENTS), agent-evolution-pool-supervisor.md (added READ_ANNOUNCEMENTS for critical watchdog + REVIEW_OWN_ANNOUNCEMENTS with 24h stale threshold); updated shared/tracking_discovery_guide.md with mandatory announcement review and consumption protocols |
| 2026-04-10 | 1.32.0 | Thirty-fifth pass (MCP token limitation and curl workaround): Added Section 6.17.0 documenting the fundamental MCP token constraint — MCP tools authenticate as a single server-level token, cannot be overridden per-call; PR Reviewer must use curl for write operations; rewrote Section 21.22 from "Total Bash Lockdown" to "Restricted Bash with curl"; **fixed 4 agent definitions**: pr-reviewer.md (added `curl *: allow`, denied `forgejo_create_pull_review` and `forgejo_create_issue_comment` MCP tools, added curl-based review/comment API call patterns with FORGEJO_REVIEWER_PAT), pr-review-pool-supervisor.md (passes all 3 reviewer credentials including PASSWORD, documents READ-via-MCP/WRITE-via-curl split), product-builder.md (passes FORGEJO_REVIEWER_PASSWORD when launching review pool), shared/credential_security.md (already had FORGEJO_REVIEWER_PASSWORD from previous pass) |
| 2026-04-10 | 1.31.0 | Thirty-fourth pass (dual-account completeness audit): Added missing `FORGEJO_REVIEWER_PASSWORD` to spec Section 6.17 env table and Appendix C (needed by ci-log-fetcher when invoked by PR Reviewer); removed ALL stale "self-approval"/"shared bot account"/"same bot account" language from 6 agent definitions and 2 spec sections: implementation-worker.md (2 approval function docstrings), shared/merge_safety.md (approval function docstring + comment), pr-merge-pool-supervisor.md (2 stale self-approval references), pr-reviewer.md (stale self-approval fallback), project-bootstrapper.md (branch protection self-approval note), shared/credential_security.md (stale comment); updated spec Sections 8.3.2 and 8.3.3 to reference dual-account architecture |
| 2026-04-10 | 1.30.0 | Thirty-third pass (dual-account architecture): Rewrote Section 6.17 from "Shared Bot Account Problem" to "Dual-Account Architecture" — introduced `FORGEJO_REVIEWER_PAT` and `FORGEJO_REVIEWER_USERNAME` environment variables for a separate reviewer Forgejo account; formal APPROVED reviews are now the PRIMARY approval path (not a workaround); updated Section 6.17.2 from "Two-Step Review Protocol" to "Dual-Account Review Protocol" (formal review first, backup comment second); added environment variables to Appendix C table; **fixed 4 agent definitions**: pr-reviewer.md (rewrote review protocol to use reviewer credentials as primary), pr-review-pool-supervisor.md (passes reviewer credentials to dispatched pr-reviewer instances), pr-merge-pool-supervisor.md (updated approval detection to recognize reviewer account as primary approver), product-builder.md (passes reviewer credentials when launching review pool supervisor); updated shared/credential_security.md with dual credential scheme |
| 2026-04-10 | 1.29.0 | Thirty-second pass (subagent specialization, eliminate duplication): Added Section 6.0 (Subagent Specialization Principle — centralize, don't duplicate); moved interval calculation from 17 duplicated agent blocks into ATM `CREATE_TRACKING_ISSUE` via new `sleep_interval_default` parameter; added ATM operation #11 `CYCLE_ANNOUNCEMENT_REVIEW` combining read + review + close in one call; updated spec Section 5.3.4 to document ATM-centralized interval calculation; updated Section 5.4 operations table to 11 operations; updated shared/tracking_discovery_guide.md to reference ATM-handled interval; **removed 17 duplicated rolling average calculation blocks** from all supervisor agents and replaced with single `--sleep-interval-default` parameter |