Fix: Add sandbox-awareness recovery nudge after repeated tool denials (#5)

[github-actions]

Summary

When the agent repeatedly hits permission denials or tool errors (e.g., trying to read files outside the workspace), it now receives a nudge after 2 consecutive failures to guide it toward finding an alternative approach within the allowed workspace.

Root Cause

The agent was not adapting when encountering repeated permission denials, continuing to retry the same failing paths instead of looking for alternatives within the sandbox.

Changes

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

Testing

• Type check passes
• Unit tests pass (32 tests)
• E2E test timeout is pre-existing (unrelated to changes)

Validation

npm run typecheck && npm test

Issue

Fixes #5

---

Automated implementation from investigation artifact

[github-actions]

🔍 Automated Code Review

Summary

Implementation correctly addresses the root cause: tracking consecutive permission denials and tool errors, then injecting a sandbox-awareness nudge after the configurable threshold is reached.

Findings

✅ Strengths

• Uses permission.replied event for direct observation of deny decisions
• Fallback to tool.execute.after hook for permission-related error patterns
• Counter resets on session busy status (active conversation)
• Cooldown period prevents nudge spam
• Configurable threshold via OPENCODE_DENY_THRESHOLD env var
• Comprehensive test coverage including error path

⚠️ Suggestions (non-blocking)

• src/deny-handler.ts:48-52 - Safe null check but could log warning for unknown sessions
• src/deny-handler.ts:76 - Cooldown of 5 minutes may be long; consider making it configurable (separate issue)

🔒 Security

• No security concerns identified
• Env vars are safely parsed as integers
• Prompt content is static, not user-controlled

Checklist

• Fix addresses root cause from investigation
• Code follows codebase patterns (uses existing throttle.ts, similar to idle-handler)
• Tests cover the change (15 tests for deny handler)
• No obvious bugs introduced
• Duplicated getOrCreateState fixed (now imports from throttle.ts)

---

Self-reviewed by Claude • Ready for human review

[github-actions]

🕰️ This pull request has been inactive for over 3 days.

@tbrandenburg - Could you please review this PR or provide an update on its status?

If this PR is no longer needed, please consider closing it to keep the repository clean.