Add sandbox-awareness recovery: nudge agent after repeated tool denials

[tbrandenburg]

Summary

When the agent repeatedly hits permission denials or tool errors (e.g. trying to read outside the workspace), it often retries the same failing path instead of adapting. A nudge after 2–3 consecutive failures would remind it that it may be in a sandboxed environment and guide it toward an alternative approach.

Motivation

Observed in practice: the agent attempted to read files under ~/.cache/ (not in the allowed directory list), triggered two permission dialogs, both were denied, and the agent kept retrying instead of looking for the same information inside the workspace. A timely injected prompt would have short-circuited this loop.

Proposed Behaviour

After 2 consecutive tool call denials or permission-related failures in the same session, inject a promptAsync nudge:

"Several tool calls have been denied or failed. You may be running in a sandboxed environment where file access is restricted to the project working directory. Avoid retrying the same path — find an alternative approach within the allowed workspace."

Reset the counter when the session transitions back to running (new user message detected via session.status).

Implementation

Two signals are available and should be combined:

Primary: permission.replied event

// event hook — fires after user responds to a permission dialog
if (event.type === "permission.replied" && event.properties.response === "deny") {
  incrementDenyCount(event.properties.sessionID)
}

EventPermissionReplied shape (from SDK types):

{ type: "permission.replied"; properties: { sessionID: string; permissionID: string; response: string } }

Directly observes the user's deny decision. No string matching needed.

Fallback: tool.execute.after hook

"tool.execute.after": async (input, output) => {
  if (/permission denied|EACCES|Operation not permitted|not allowed/i.test(output.output)) {
    incrementToolErrorCount(input.sessionID)
  }
}

Catches cases where the permission system is bypassed entirely (auto-deny rules, OS-level sandbox restrictions). output.output is the raw string result of the tool call.

Reset on new activity

// in the existing event handler
if (event.type === "session.status" && event.properties.status.type === "running") {
  resetDenyCounts(event.properties.sessionID)
}

Threshold

Default: 2 consecutive failures before nudging. Configurable via OPENCODE_DENY_THRESHOLD env var (same pattern as OPENCODE_IDLE_THRESHOLD_MS).

Out of scope

• Auto-allowing or auto-denying permissions — the plugin must never change output.status in permission.ask; it only observes outcomes.
• Permanent system prompt injection via experimental.chat.system.transform — preventive hints add tokens to every request regardless of whether an issue exists; the reactive approach is preferred.

Acceptance Criteria

• After 2 consecutive denials/errors in a session, a nudge prompt is injected via promptAsync
• Counter resets when the session goes back to running
• Threshold is configurable via env var
• Unit tests cover: single denial (no nudge), threshold reached (nudge fires), reset on running, tool.execute.after error pattern matching
• E2E test is not required (permission dialogs are hard to trigger programmatically without mocking)

[github-actions]

Investigation: Add sandbox-awareness recovery: nudge agent after repeated tool denials

Issue: #5 (#5)
Type: ENHANCEMENT
Investigated: 2026-03-31T00:00:00.000Z

Assessment

Metric	Value	Reasoning
Priority	HIGH	Prevents repeated permission denial loops, directly addresses observed agent behavior issue in production
Complexity	MEDIUM	3 files to modify (types.ts, throttle.ts, index.ts), 1 new file (denial-handler.ts), plus test file
Confidence	HIGH	Clear event types documented in issue (permission.replied, tool.execute.after, session.status), well-defined existing patterns to follow

---

Problem Statement

The agent repeatedly retries failing operations (e.g., file access to restricted paths) after permission denials instead of adapting. A nudge after 2 consecutive denials would redirect the agent to find alternative approaches within the allowed workspace.

---

Analysis

Change Rationale

The plugin needs to track consecutive permission denials and inject a recovery prompt when a threshold is reached. This requires:

1. Adding denial-tracking fields to SessionState
2. Creating a new handler for permission events and tool errors
3. Adding env var configuration for the threshold
4. Resetting counters on session restart

Evidence Chain

ISSUE REQUIREMENT: After 2 consecutive denials/errors, inject a nudge prompt
↓ BECAUSE: The agent needs awareness of sandbox restrictions

PRIMARY SIGNAL: permission.replied event
Evidence: src/index.ts:8 - existing event hook pattern with event.type filtering

FALLBACK SIGNAL: tool.execute.after hook
Evidence: src/idle-handler.ts:19 - pattern for filtering event.type in the event hook

STATE MANAGEMENT: Session state in Map
Evidence: src/types.ts:19 - sessionStates = new Map<string, SessionState>()

PROMPT INJECTION: client.session.promptAsync
Evidence: src/idle-handler.ts:48-52 - exact pattern for calling promptAsync

ENV CONFIG: process.env["OPENCODE_*"] pattern
Evidence: src/types.ts:9-12 - getIdleThreshold() function as template

Affected Files

File	Lines	Action	Description
src/types.ts	1-19	UPDATE	Add denial tracking fields and constants
src/throttle.ts	9-20	UPDATE	Add denial fields to getOrCreateState
src/index.ts	1-14	UPDATE	Register new denial handler
src/denial-handler.ts	NEW	CREATE	New handler for denial events
src/denial-handler.test.ts	NEW	CREATE	Unit tests for denial handler

Integration Points

• src/index.ts:8 - event hook calls handleIdleEvent
• src/idle-handler.ts:15 - handleIdleEvent signature as template
• src/types.ts:7 - SessionState interface for new fields
• src/throttle.ts:9 - getOrCreateState initializes session state

Git History

• Last modified: Initial implementation - no prior history for this project
• Implication: New feature implementation, no regression concerns

---

Implementation Plan

Step 1: Add denial tracking fields and constants to types.ts

File: src/types.ts
Lines: 1-19
Action: UPDATE

Current code:

export interface SessionState {
  lastContinuation: number  // ms timestamp of last nudge prompt (0 = never)
  hourlyCount: number       // number of nudges issued in current hour window
  hourStart: number         // ms timestamp marking start of current hour window
  lastIdleSeen: number      // ms timestamp when session.idle was first observed (0 = not idle)
  lastUserMessage: number   // ms timestamp of last incoming user message (0 = never)
}

Required change:

export interface SessionState {
  lastContinuation: number  // ms timestamp of last nudge prompt (0 = never)
  hourlyCount: number       // number of nudges issued in current hour window
  hourStart: number         // ms timestamp marking start of current hour window
  lastIdleSeen: number      // ms timestamp when session.idle was first observed (0 = not idle)
  lastUserMessage: number   // ms timestamp of last incoming user message (0 = never)
  // Denial tracking
  consecutiveDenials: number      // count of consecutive permission/tool denials
  lastDenialTime: number           // ms timestamp of last denial
  lastDenialNudge: number          // ms timestamp of last denial nudge
}

Also add at end of file (before sessionStates):

export function getDenialThreshold(): number {
  const env = process.env["OPENCODE_DENIAL_THRESHOLD"]
  return env !== undefined ? parseInt(env, 10) : 2  // default: nudge after 2 denials
}
export const DENIAL_COOLDOWN = 10 * 60 * 1000        // 600,000ms — minimum gap between denial nudges
export const DENIAL_RECOVERY_PROMPT =
  "Several tool calls have been denied or failed. You may be running in a sandboxed environment where file access is restricted to the project working directory. Avoid retrying the same path — find an alternative approach within the allowed workspace."

Why: Extends existing state interface with denial tracking fields, adds env-configurable threshold following the getIdleThreshold() pattern.

---

Step 2: Initialize denial fields in getOrCreateState

File: src/throttle.ts
Lines: 9-20
Action: UPDATE

Current code:

export function getOrCreateState(sessionID: string): SessionState {
  if (!sessionStates.has(sessionID)) {
    sessionStates.set(sessionID, {
      lastContinuation: 0,
      hourlyCount: 0,
      hourStart: 0,
      lastIdleSeen: 0,
      lastUserMessage: 0,
    })
  }
  return sessionStates.get(sessionID)!
}

Required change:

export function getOrCreateState(sessionID: string): SessionState {
  if (!sessionStates.has(sessionID)) {
    sessionStates.set(sessionID, {
      lastContinuation: 0,
      hourlyCount: 0,
      hourStart: 0,
      lastIdleSeen: 0,
      lastUserMessage: 0,
      consecutiveDenials: 0,
      lastDenialTime: 0,
      lastDenialNudge: 0,
    })
  }
  return sessionStates.get(sessionID)!
}

Why: Initialize new denial tracking fields to 0 for new sessions.

---

Step 3: Create denial-handler.ts

File: src/denial-handler.ts
Action: CREATE

import type { Event } from "@opencode-ai/sdk"
import type { PluginInput } from "@opencode-ai/plugin"
import {
  getDenialThreshold,
  DENIAL_COOLDOWN,
  DENIAL_RECOVERY_PROMPT,
} from "./types.js"
import { getOrCreateState } from "./throttle.js"

type Client = PluginInput["client"]

function log(client: Client, level: "debug" | "info" | "warn" | "error", message: string, extra?: Record<string, unknown>): void {
  client.app.log({ body: { service: "opencode-nudge", level, message, extra } })
}

const PERMISSION_DENIED_PATTERNS = /permission denied|EACCES|Operation not permitted|not allowed/i

export async function handleDenialEvent(
  { event }: { event: Event },
  client: Client
): Promise<void> {
  const sessionID = extractSessionID(event)
  if (!sessionID) return

  const state = getOrCreateState(sessionID)
  const now = Date.now()

  // Handle session.status reset
  if (event.type === "session.status" && event.properties.status?.type === "running") {
    state.consecutiveDenials = 0
    state.lastDenialTime = 0
    log(client, "debug", "session running — denial counter reset", { sessionID })
    return
  }

  // Check for permission.replied with deny
  if (event.type === "permission.replied" && event.properties.response === "deny") {
    state.consecutiveDenials++
    state.lastDenialTime = now
    log(client, "debug", "permission denied", { sessionID, consecutiveDenials: state.consecutiveDenials })
    await maybeInjectDenialNudge(state, sessionID, now, client)
    return
  }

  // Check tool.execute.after for error patterns
  if (event.type === "tool.execute.after" && PERMISSION_DENIED_PATTERNS.test(event.properties?.output ?? "")) {
    state.consecutiveDenials++
    state.lastDenialTime = now
    log(client, "debug", "tool error detected", { sessionID, consecutiveDenials: state.consecutiveDenials })
    await maybeInjectDenialNudge(state, sessionID, now, client)
    return
  }
}

async function maybeInjectDenialNudge(
  state: ReturnType<typeof import("./throttle.js").getOrCreateState>,
  sessionID: string,
  now: number,
  client: Client
): Promise<void> {
  if (state.consecutiveDenials < getDenialThreshold()) return

  // Check cooldown
  if (state.lastDenialNudge > 0 && now - state.lastDenialNudge < DENIAL_COOLDOWN) {
    log(client, "debug", "denial threshold reached but throttled", { sessionID })
    return
  }

  try {
    await client.session.promptAsync({
      path: { id: sessionID },
      body: { parts: [{ type: "text", text: DENIAL_RECOVERY_PROMPT }] },
    })
    state.lastDenialNudge = now
    state.consecutiveDenials = 0
    log(client, "info", "denial recovery prompt injected", { sessionID })
  } catch (err) {
    log(client, "error", "failed to inject denial recovery prompt", { sessionID, err: String(err) })
  }
}

function extractSessionID(event: Event): string | null {
  if (event.type === "permission.replied") return event.properties.sessionID ?? null
  if (event.type === "tool.execute.after") return event.properties.sessionID ?? null
  if (event.type === "session.status") return event.properties.sessionID ?? null
  return null
}

Why: Implements the primary and fallback signals for denial tracking, with session reset handling.

---

Step 4: Register denial handler in index.ts

File: src/index.ts
Lines: 1-14
Action: UPDATE

Current code:

import type { Plugin } from "@opencode-ai/plugin"
import { handleIdleEvent, handleUserMessage } from "./idle-handler.js"

export const OpencodeNudgePlugin: Plugin = async (input) => {
  input.client.app.log({ body: { service: "opencode-nudge", level: "info", message: "plugin loaded" } })

  return {
    event: ({ event }) => handleIdleEvent({ event }, input.client),
    "chat.message": (messageInput) => {
      handleUserMessage({ sessionID: messageInput.sessionID })
      return Promise.resolve()
    },
  }
}

Required change:

import type { Plugin } from "@opencode-ai/plugin"
import { handleIdleEvent, handleUserMessage } from "./idle-handler.js"
import { handleDenialEvent } from "./denial-handler.js"

export const OpencodeNudgePlugin: Plugin = async (input) => {
  input.client.app.log({ body: { service: "opencode-nudge", level: "info", message: "plugin loaded" } })

  return {
    event: ({ event }) => {
      handleIdleEvent({ event }, input.client)
      handleDenialEvent({ event }, input.client)
    },
    "chat.message": (messageInput) => {
      handleUserMessage({ sessionID: messageInput.sessionID })
      return Promise.resolve()
    },
  }
}

Why: Registers the new denial handler in the event hook pipeline.

---

Step 5: Create denial-handler.test.ts

File: src/denial-handler.test.ts
Action: CREATE

import { describe, it, expect, beforeEach, afterEach, mock } from "bun:test"
import { handleDenialEvent } from "./denial-handler.js"
import { sessionStates, getDenialThreshold } from "./types.js"
import { getOrCreateState } from "./throttle.js"

function makeClient(promptFn = mock(() => Promise.resolve())) {
  return {
    app: { log: mock(() => undefined) },
    session: { promptAsync: promptFn },
  } as any
}

let savedThresholdEnv: string | undefined
function isolateDenialThresholdEnv() {
  beforeEach(() => {
    savedThresholdEnv = process.env["OPENCODE_DENIAL_THRESHOLD"]
    delete process.env["OPENCODE_DENIAL_THRESHOLD"]
  })
  afterEach(() => {
    if (savedThresholdEnv !== undefined) {
      process.env["OPENCODE_DENIAL_THRESHOLD"] = savedThresholdEnv
    } else {
      delete process.env["OPENCODE_DENIAL_THRESHOLD"]
    }
  })
}

describe("handleDenialEvent", () => {
  beforeEach(() => sessionStates.clear())

  describe("single denial — no nudge", () => {
    isolateDenialThresholdEnv()

    it("does not prompt on first denial", async () => {
      const client = makeClient()
      await handleDenialEvent(
        { event: { type: "permission.replied", properties: { sessionID: "s1", response: "deny" } } as any },
        client as any
      )
      expect(client.session.promptAsync).not.toHaveBeenCalled()
      expect(getOrCreateState("s1").consecutiveDenials).toBe(1)
    })
  })

  describe("threshold reached — nudge fires", () => {
    isolateDenialThresholdEnv()

    it("prompts after two denials", async () => {
      const promptFn = mock(() => Promise.resolve())
      const client = makeClient(promptFn)
      
      await handleDenialEvent(
        { event: { type: "permission.replied", properties: { sessionID: "s2", response: "deny" } } as any },
        client as any
      )
      await handleDenialEvent(
        { event: { type: "permission.replied", properties: { sessionID: "s2", response: "deny" } } as any },
        client as any
      )
      
      expect(promptFn).toHaveBeenCalledTimes(1)
      const calls = promptFn.mock.calls as unknown as Array<[{ path: { id: string }; body: { parts: Array<{ text: string }> } }]>
      expect(calls[0]![0]!.path.id).toBe("s2")
      expect(calls[0]![0]!.body.parts[0]!.text).toContain("sandboxed environment")
    })

    it("resets counter after nudge", async () => {
      const client = makeClient()
      await handleDenialEvent(
        { event: { type: "permission.replied", properties: { sessionID: "s3", response: "deny" } } as any },
        client as any
      )
      await handleDenialEvent(
        { event: { type: "permission.replied", properties: { sessionID: "s3", response: "deny" } } as any },
        client as any
      )
      expect(getOrCreateState("s3").consecutiveDenials).toBe(0)
    })
  })

  describe("reset on running", () => {
    isolateDenialThresholdEnv()

    it("resets consecutiveDenials when session goes to running", async () => {
      const client = makeClient()
      const state = getOrCreateState("s4")
      state.consecutiveDenials = 5
      
      await handleDenialEvent(
        { event: { type: "session.status", properties: { sessionID: "s4", status: { type: "running" } } } as any },
        client as any
      )
      
      expect(state.consecutiveDenials).toBe(0)
    })
  })

  describe("tool.execute.after error pattern matching", () => {
    isolateDenialThresholdEnv()

    it("increments counter on 'permission denied' error", async () => {
      const client = makeClient()
      await handleDenialEvent(
        { event: { type: "tool.execute.after", properties: { sessionID: "s5", output: "Error: permission denied" } } as any },
        client as any
      )
      expect(getOrCreateState("s5").consecutiveDenials).toBe(1)
    })

    it("increments counter on EACCES error", async () => {
      const client = makeClient()
      await handleDenialEvent(
        { event: { type: "tool.execute.after", properties: { sessionID: "s6", output: "EACCES: permission denied" } } as any },
        client as any
      )
      expect(getOrCreateState("s6").consecutiveDenials).toBe(1)
    })

    it("does not increment on successful tool output", async () => {
      const client = makeClient()
      await handleDenialEvent(
        { event: { type: "tool.execute.after", properties: { sessionID: "s7", output: "File read successfully" } } as any },
        client as any
      )
      expect(getOrCreateState("s7").consecutiveDenials).toBe(0)
    })
  })

  describe("env var configuration", () => {
    it("uses env var for threshold when set", async () => {
      process.env["OPENCODE_DENIAL_THRESHOLD"] = "3"
      const promptFn = mock(() => Promise.resolve())
      const client = makeClient(promptFn)
      
      // 2 denials should not trigger (threshold is 3)
      await handleDenialEvent(
        { event: { type: "permission.replied", properties: { sessionID: "s8", response: "deny" } } as any },
        client as any
      )
      await handleDenialEvent(
        { event: { type: "permission.replied", properties: { sessionID: "s8", response: "deny" } } as any },
        client as any
      )
      expect(promptFn).not.toHaveBeenCalled()
      
      // 3rd denial should trigger
      await handleDenialEvent(
        { event: { type: "permission.replied", properties: { sessionID: "s8", response: "deny" } } as any },
        client as any
      )
      expect(promptFn).toHaveBeenCalledTimes(1)
      
      delete process.env["OPENCODE_DENIAL_THRESHOLD"]
    })
  })
})

Why: Comprehensive unit tests covering all acceptance criteria from the issue.

---

Patterns to Follow

From codebase — mirror these exactly:

// SOURCE: src/idle-handler.ts:11-13
// Pattern for logging
function log(client: Client, level: "debug" | "info" | "warn" | "error", message: string, extra?: Record<string, unknown>): void {
  client.app.log({ body: { service: "opencode-nudge", level, message, extra } })
}

// SOURCE: src/types.ts:9-12
// Pattern for env var configuration
export function getIdleThreshold(): number {
  const env = process.env["OPENCODE_IDLE_THRESHOLD_MS"]
  return env !== undefined ? parseInt(env, 10) : 5 * 60 * 1000  // 300,000ms default
}

// SOURCE: src/idle-handler.test.ts:7-12
// Pattern for mock client factory
function makeClient(promptFn = mock(() => Promise.resolve())) {
  return {
    app: { log: mock(() => undefined) },
    session: { promptAsync: promptFn },
  } as any
}

// SOURCE: src/idle-handler.test.ts:16-29
// Pattern for env isolation in tests
let savedThresholdEnv: string | undefined
function isolateThresholdEnv() {
  beforeEach(() => {
    savedThresholdEnv = process.env["OPENCODE_IDLE_THRESHOLD_MS"]
    delete process.env["OPENCODE_IDLE_THRESHOLD_MS"]
  })
  afterEach(() => {
    if (savedThresholdEnv !== undefined) {
      process.env["OPENCODE_IDLE_THRESHOLD_MS"] = savedThresholdEnv
    } else {
      delete process.env["OPENCODE_IDLE_THRESHOLD_MS"]
    }
  })
}

---

Edge Cases & Risks

Risk/Edge Case	Mitigation
Event type shapes not matching SDK types	Use optional chaining (?.) and type casting for safety
Session ID missing from event	extractSessionID returns null, handler exits early
promptAsync throws	Wrap in try/catch, log error, don't crash handler
Threshold of 0 or invalid env value	parseInt returns NaN, which fails < getDenialThreshold() comparison
Very rapid denials (race condition)	Counter increments atomically via JS single-threaded nature

---

Validation

Automated Checks

cd opencode-nudge
bun run typecheck
bun test src/denial-handler.test.ts
bun test src/idle-handler.test.ts  # ensure no regression
bun test src/throttle.test.ts      # ensure no regression

Manual Verification

1. Load plugin in test environment with permission dialogs
2. Deny 2 permission requests - verify recovery prompt appears
3. Check logs for "denial recovery prompt injected"
4. Verify counter resets when session.status becomes running

---

Scope Boundaries

IN SCOPE:

• Tracking permission.replied with deny response
• Tracking tool.execute.after errors matching denial patterns
• Resetting counters on session.status → running
• Configurable threshold via OPENCODE_DENIAL_THRESHOLD env var
• Recovery prompt injection via promptAsync

OUT OF SCOPE (do not touch):

• Auto-allowing or auto-denying permissions (per issue specification)
• Using experimental.chat.system.transform for permanent prompt injection
• E2E tests for permission dialogs (per issue: "hard to trigger programmatically")
• Changing output.status in permission.ask handlers

---

Metadata

• Investigated by: GHAR
• Timestamp: 2026-03-31T00:00:00.000Z
• Artifact: .ghar/issues/issue-5.md

[tbrandenburg]

/ghar-issue-fix 5

[github-actions]

🤖 OpenCode Execution Complete

Command: /ghar-issue-fix
Run ID: 23819698894
Status: ✅ Completed

Results

Now I understand the codebase. Let me implement the sandbox-awareness feature.

Implementation Complete

Issue: #5 - Add sandbox-awareness recovery: nudge agent after repeated tool denials
Branch: fix/issue-5-sandbox-awareness
PR: #6 - #6

Changes Made

File	Change
src/deny-handler.ts	New - permission denial and tool error tracking logic
src/deny-handler.test.ts	New - 15 unit tests
src/types.ts	Added deny state fields and threshold config
src/throttle.ts	Added deny state fields to session state
src/index.ts	Registered event and tool hooks

Validation

Check	Result
Type check	✅ Pass
Unit tests (32)	✅ Pass
E2E timeout	Pre-existing issue

Self-Review

• Fix addresses root cause via permission.replied event and tool.execute.after hook
• Code follows existing patterns (similar to idle-handler.ts)
• Tests cover: single denial, threshold reached, reset on busy, error pattern matching, rejection path
• Fixed code duplication (imported getOrCreateState from throttle.ts)

Acceptance Criteria Met

• ✅ After 2 consecutive denials/errors, a nudge prompt is injected via promptAsync
• ✅ Counter resets when session goes back to busy (active)
• ✅ Threshold configurable via OPENCODE_DENY_THRESHOLD env var
• ✅ Unit tests cover all specified cases

[github-actions]

🕰️ This issue has been inactive for over 3 days.

@tbrandenburg - Could you provide an update on this issue?

If this issue is resolved or no longer relevant, please consider closing it.