Skills: forbid `mcp__forgejo__update_file` for code edits (use Edit/Write + git CLI)

claude-desktop commented

2026-04-19 00:56:06 +00:00

Collaborator

User story

As the operator, I want the code-flow skills (implement,
address-review, rebase, fix-ci) to explicitly steer agents
toward Edit / Write + git CLI for code changes, and reserve
mcp__forgejo__* for issue / PR / comment operations only — so
that Sonnet agents stop hitting the prompt-token limit on multi-turn
tasks that involve large files.

What happened (concrete)

#77 was assigned to dev as the first container-mode validation for
a code agent. Dev ran for 51 turns, landed 3 of 4 commits correctly
(1cd3633, 3859f04, b34dd47 on branch dev/77), then died on
turn 52 with Prompt is too long when it tried to call:

mcp__forgejo__update_file(
  owner="charles",
  repo="claude-hooks",
  filePath="src/container.test.ts",
  branch_name="dev/77",
  sha="...",
  message="test(container): remove defaultHostCredentialsPath() tests",
  content="<entire ~400-line file body inlined as a string>"
)

The content argument was the full file body. Combined with the
prior 51 turns of conversation, the aggregate token count blew past
Sonnet's prompt window. The agent already had the file cloned in its
worktree (/state/worktrees/dev/charles__claude-hooks__dev%2F77/).
It could have used Edit for a targeted diff, or Write to
overwrite locally and then Bash for git add / commit / push.

The work product is otherwise correct — container-mode infrastructure
worked, the implementation logic was right. This is a skill-guidance
bug, not an infra bug.

Why this class of failure matters

Every Sonnet code agent (dev today; reviewer for its own PRs
eventually) runs on a ~200k prompt budget. A large file × several
turns of context = overflow. The failure mode is silent until it
happens, and when it does the agent is mid-task. The cheapest
prevention is a skill-level rule: do not use Forgejo's RPC
update_file / create_file for code changes. They exist for
out-of-band fixes (web UI edits, hotfixes with no local clone) and
are wrong tools when the worktree is right there.

Acceptance criteria

Skills — add an explicit tool-choice rule

skills/implement.md — add a section near the top (right after
the workflow) that names the tools for each operation:
- Code changes → Edit (diff) or Write (full overwrite,
small files only) in the local worktree + Bash for
git add, git commit, git push.
- Issue / PR / comment operations → mcp__forgejo__*
(open PR, assign labels, update issue body, post comment).
- Never use mcp__forgejo__update_file /
mcp__forgejo__create_file / mcp__forgejo__delete_file for
modifications to the repo the agent is cloned into —
they're for working on repos without a local checkout and
blow the prompt on files > ~200 lines.
Same rule repeated in skills/address-review.md,
skills/rebase.md, skills/fix-ci.md, and the -delta.md
variants where present. One canonical paragraph copy-pasted so
every skill's front matter agrees.

Dashboard-visible failure mode

src/agent-runner.ts / main.ts log the specific
Prompt is too long error with a hint pointing at this
ticket's rule when it fires. The current task record stores
the last SDK error, so the hint surfaces on the task detail
view in the monitor UI.

Tests

No new unit tests — this is a prompt-level rule, not code.
The regression catch is operational (agent's next task
completes without overflow). We'll know it landed when a
large-file cleanup on dev or reviewer finishes in < 20
turns instead of 52.

Out of scope

Enforcing the rule by blocking the tool. We could block
mcp__forgejo__update_file for the worktree's own repo in
canUseTool, but that's heavier than necessary and would trip
legitimate out-of-band edits in the future. Skill-level guidance
first; enforcement only if guidance isn't enough.
Rewriting every skill. The rule is short; it goes into the
existing skills as a paragraph, not a restructure.
The update_file MCP tool itself. No change to forgejo-mcp.
The tool is correct; the usage pattern was wrong.

References

Issue #77 / PR #78 — the dispatch that surfaced this.
Failure snippet: dev task d9f5d568-bb75-4467-8438-4ca16ef13d2b,
turn 52, Prompt is too long → API error: invalid_request.
Skills to touch: skills/{implement,address-review,rebase,fix-ci}.md
plus the -delta.md variants.

Dependencies

Blocked by: nothing.
Blocks: future large-file code tasks on Sonnet agents.
Branch off: main.

## User story As the **operator**, I want the code-flow skills (`implement`, `address-review`, `rebase`, `fix-ci`) to explicitly steer agents toward **Edit / Write + git CLI** for code changes, and reserve `mcp__forgejo__*` for **issue / PR / comment** operations only — so that Sonnet agents stop hitting the prompt-token limit on multi-turn tasks that involve large files. ## What happened (concrete) #77 was assigned to `dev` as the first container-mode validation for a code agent. Dev ran for 51 turns, landed 3 of 4 commits correctly (`1cd3633`, `3859f04`, `b34dd47` on branch `dev/77`), then died on turn 52 with `Prompt is too long` when it tried to call: ``` mcp__forgejo__update_file( owner="charles", repo="claude-hooks", filePath="src/container.test.ts", branch_name="dev/77", sha="...", message="test(container): remove defaultHostCredentialsPath() tests", content="<entire ~400-line file body inlined as a string>" ) ``` The `content` argument was the full file body. Combined with the prior 51 turns of conversation, the aggregate token count blew past Sonnet's prompt window. The agent already had the file cloned in its worktree (`/state/worktrees/dev/charles__claude-hooks__dev%2F77/`). It could have used `Edit` for a targeted diff, or `Write` to overwrite locally and then `Bash` for `git add / commit / push`. The work product is otherwise correct — container-mode infrastructure worked, the implementation logic was right. This is a skill-guidance bug, not an infra bug. ## Why this class of failure matters Every Sonnet code agent (`dev` today; `reviewer` for its own PRs eventually) runs on a ~200k prompt budget. A large file × several turns of context = overflow. The failure mode is silent until it happens, and when it does the agent is mid-task. The cheapest prevention is a skill-level rule: **do not use Forgejo's RPC `update_file` / `create_file` for code changes**. They exist for out-of-band fixes (web UI edits, hotfixes with no local clone) and are wrong tools when the worktree is right there. ## Acceptance criteria ### Skills — add an explicit tool-choice rule - [ ] `skills/implement.md` — add a section near the top (right after the workflow) that names the tools for each operation: - **Code changes** → `Edit` (diff) or `Write` (full overwrite, small files only) in the **local worktree** + `Bash` for `git add`, `git commit`, `git push`. - **Issue / PR / comment operations** → `mcp__forgejo__*` (open PR, assign labels, update issue body, post comment). - **Never** use `mcp__forgejo__update_file` / `mcp__forgejo__create_file` / `mcp__forgejo__delete_file` for modifications to the repo the agent is cloned into — they're for working on repos without a local checkout and blow the prompt on files > ~200 lines. - [ ] Same rule repeated in `skills/address-review.md`, `skills/rebase.md`, `skills/fix-ci.md`, and the `-delta.md` variants where present. One canonical paragraph copy-pasted so every skill's front matter agrees. ### Dashboard-visible failure mode - [ ] `src/agent-runner.ts` / `main.ts` log the specific `Prompt is too long` error with a hint pointing at this ticket's rule when it fires. The current task record stores the last SDK error, so the hint surfaces on the task detail view in the monitor UI. ### Tests - [ ] No new unit tests — this is a prompt-level rule, not code. The regression catch is operational (agent's next task completes without overflow). We'll know it landed when a large-file cleanup on `dev` or `reviewer` finishes in < 20 turns instead of 52. ## Out of scope - **Enforcing the rule by blocking the tool.** We could block `mcp__forgejo__update_file` for the worktree's own repo in `canUseTool`, but that's heavier than necessary and would trip legitimate out-of-band edits in the future. Skill-level guidance first; enforcement only if guidance isn't enough. - **Rewriting every skill.** The rule is short; it goes into the existing skills as a paragraph, not a restructure. - **The `update_file` MCP tool itself.** No change to forgejo-mcp. The tool is correct; the usage pattern was wrong. ## References - Issue #77 / PR #78 — the dispatch that surfaced this. - Failure snippet: dev task `d9f5d568-bb75-4467-8438-4ca16ef13d2b`, turn 52, `Prompt is too long` → `API error: invalid_request`. - Skills to touch: `skills/{implement,address-review,rebase,fix-ci}.md` plus the `-delta.md` variants. ## Dependencies - **Blocked by:** nothing. - **Blocks:** future large-file code tasks on Sonnet agents. - **Branch off:** `main`.

claude-desktop added the

area:agents

type:user-story

labels

2026-04-19 00:56:10 +00:00