restricted-tool-triage

Restricted Tool Triage

Use this skill whenever you (the agent) are executing inside a gh-aw workflow whose frontmatter declares a narrow tools: allowlist (e.g. a short bash: [...] list, a scoped MCP toolsets, or no read/shell at all) and you hit — or are at risk of hitting — a "permission denied" / tool-denial response from the harness.

Why this matters

gh-aw enforces a hard, non-renewable denial budget per session (commonly 3 denied tool calls). Once the threshold is reached, the harness emits guard.tool_denials_exceeded and aborts the entire session immediately — no further turns, no partial credit, no chance to recover. Treat every tool denial as spending down a scarce budget, not as a way to probe what's allowed.

Triggers

• A tool call returns "permission denied by workflow tool permissions" or similar.
• You are about to try a shell/read/write command and are unsure if it's in the declared tools: allowlist.
• The workflow frontmatter shows a short/explicit bash: list, restrictive MCP toolsets, or omits edit/bash entirely.

Procedure

1. Read the allowlist first, before acting. Before issuing any shell/file/MCP command, check the workflow's declared tools: block (frontmatter bash: [...], edit:, MCP toolsets:, etc.) if visible in context, or infer it from the first denial message, which echoes the exact denied command. Do not assume general-purpose shell access is available just because the environment looks like a normal shell.

2. On the first denial, stop and pivot — do not retry variants. A denial is not a request to try a slightly different phrasing of the same disallowed command (e.g. don't go from git status to git status --short to git diff --stat as three separate attempts). Instead:

   • Identify the capability you actually need (e.g. "see which files changed").
   • Map it to a tool/command explicitly present in the allowlist (e.g. use git diff --name-only if git diff:* is allowed but git status is not; use the already-available MCP toolset instead of raw read/shell for file or repo introspection).
   • If no allowed tool can achieve the capability, stop attempting workarounds for that capability and route around it (skip the sub-task, or note the limitation in your output) rather than spending more of the denial budget.