Deadline Pressure

OpenCode plugin that warns agents about time budget consumption, enforces phased lockdowns, and nudges handoff before the deadline expires.

Features

• Tracks the execution time budget of the agent using a sentinel file (.opencode-deadline-start) for cross-process persistence.
• Fires tiered warnings as the agent approaches its timeout limit (info → warning → critical).
• Enforces investigation lockdown at 75% budget — diagnostic/exploration bash commands are blocked.
• Enforces full lockdown at 90% budget — only write, edit, build, and run commands are permitted.
• Phase-aware exemptions — during verify_* and fix_* phases, read-only tools and test-running commands are exempted from lockdown so the agent can verify deliverables and test fixes.
• Recognizes common test runners (pytest, npm test, cargo test, go test, make test) as "run" intent, allowing them during fix phases even under full lockdown.
• Configurable time limits and threshold percentages.

Installation

npm install opencode-deadline-pressure

Quick Start

Add to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "opencode-deadline-pressure"
  ]
}

To pass configuration options, use the tuple form:

{
  "plugin": [
    ["opencode-deadline-pressure", { "budgetMs": 1800000 }]
  ]
}

Table of Contents

• Features
• Installation
• Quick Start
• How It Works
  • Sentinel File
  • Threshold Tiers
  • Intent Classification
  • Phase Awareness
• Configuration
  • Options
  • Examples
• Limitations
• Programmatic Usage
• License

How It Works

The plugin hooks into three points of OpenCode's tool lifecycle:

• event (on step-finish): Checks elapsed time against the budget and fires threshold warnings.
• tool.execute.before: Enforces lockdown restrictions based on the current tier and phase.
• tool.execute.after: Injects non-blocking warnings into tool output.

Sentinel File

The plugin writes a sentinel file (.opencode-deadline-start) in the working directory on first init. This file contains the Unix timestamp (milliseconds) when the deadline clock started. On subsequent loads, the plugin reads this file to restore the start time, ensuring the clock persists across process restarts (e.g., when the orchestrator launches a new opencode session for verification or fixing).

If the sentinel file is missing or corrupt, the plugin creates a new one with the current time.

Threshold Tiers

The plugin has three default threshold tiers:

Tier	% of budget	Severity	What happens
1	50%	info	Non-blocking warning: "You should be writing your solution file soon."
2	75%	warning	Investigation lockdown: diagnostic/exploration bash commands are blocked. Non-blocking.
3	90%	critical	Full lockdown: read/grep/glob tools blocked, investigate-intent bash blocked. Blocking. Write/edit always allowed.

Investigation lockdown (Tier 2): Bash commands classified as "investigate" intent (e.g., ls, cat, grep, find) are blocked with an error. The agent must focus on writing, compiling, and testing.

Full lockdown (Tier 3): All read-only tools (read, grep, glob) and investigate-intent bash commands are blocked. Only write, edit, and bash commands with "build" or "run" intent are permitted. This forces the agent to finalize its solution.

Write/edit are never blocked. Even at critical threshold, the agent can always write or edit files — it just can't explore or diagnose anymore.

Intent Classification

The plugin classifies bash commands into five intents to determine which are blocked during lockdown:

Intent	Examples	Blocked in investigation lockdown?	Blocked in full lockdown?
setup	pip install, npm install, apt-get install	No	No
build	gcc, make, cmake, tsc, cargo build	No	No
run	python3 solution.py, ./a.out, pytest, npm test	No	No (during fix phase)
write	heredoc redirects, cp/mv to /app/	No	No
investigate	ls, cat, grep, find, which	Yes	Yes

Test runner recognition: The following commands are classified as run intent (not investigate):

• pytest, python -m pytest
• npm test, npm run test
• cargo test
• go test
• make test

This ensures that running tests is permitted during fix phases even under full lockdown.

Phase Awareness

The plugin reads the AGENT_PHASE environment variable to adjust lockdown behavior during different phases of an agent pipeline (e.g., FrankCode's main → verify → fix cycle).

Phase prefix	Read/grep/glob	Investigate bash	Run bash (tests)	Write/edit
verify_*	✅ Allowed	✅ Allowed	✅ Allowed	✅ Allowed
fix_*	❌ Blocked (full lockdown)	❌ Blocked (full lockdown)	✅ Allowed	✅ Allowed
main or unset	❌ Blocked (full lockdown)	❌ Blocked (full lockdown)	❌ Blocked (full lockdown)	✅ Allowed

Why: During verification phases, the agent's primary job is to read deliverables and test output — activities that would normally be blocked by full lockdown. During fix phases, the agent needs to run tests to verify its fixes. The phase awareness feature ensures these essential activities are not blocked by the deadline pressure.

How to set the phase: The orchestrator (e.g., FrankCode) sets AGENT_PHASE in the environment before launching each opencode session. The value is typically main, verify_1, verify_2, fix_1, fix_2, etc.

AGENT_PHASE=verify_1 opencode run "verify the deliverables..."

Configuration

Options

Option	Type	Default	Description
budgetMs	number	2400000 (40 min)	Total time budget in milliseconds
thresholds	ThresholdConfig[]	(see below)	Custom threshold tiers

Default thresholds:

[
  { percent: 50, severity: "info",    blocking: false, investigationLockdown: false, fullLockdown: false },
  { percent: 75, severity: "warning", blocking: false, investigationLockdown: true,  fullLockdown: false },
  { percent: 90, severity: "critical",blocking: true,  investigationLockdown: false, fullLockdown: true  },
]

Each ThresholdConfig has:

Field	Type	Description
percent	number	Percentage of budget at which this tier fires
severity	"info" | "warning" | "critical"	Severity level (affects emoji prefix)
message	string	Warning message template with {percent}, {elapsed}, {remaining} placeholders
blocking	boolean	If true, the warning is delivered as a thrown error on the next tool call
investigationLockdown	boolean	If true, activates investigation lockdown at this tier
fullLockdown	boolean	If true, activates full lockdown at this tier

Examples

Custom budget (30 minutes):

{
  "plugin": [
    ["opencode-deadline-pressure", { "budgetMs": 1800000 }]
  ]
}

Custom thresholds:

{
  "plugin": [
    ["opencode-deadline-pressure", {
      "budgetMs": 3600000,
      "thresholds": [
        { "percent": 33, "severity": "info", "message": "Third of budget used.", "blocking": false },
        { "percent": 80, "severity": "critical", "message": "Almost out of time!", "blocking": true, "fullLockdown": true }
      ]
    }]
  ]
}

Limitations

• Sentinel file is per-directory. The .opencode-deadline-start file is created in the working directory. If the working directory changes between sessions, the start time is reset.
• Phase awareness requires AGENT_PHASE env var. Without it, all lockdowns apply at full strength regardless of phase.
• Intent classification is regex-based. Complex commands (e.g., bash -c "pytest && ls") may be misclassified. The classifier checks the first command token.
• No per-tool exemptions. You cannot whitelist specific files or commands. The phase-based exemptions are the only way to bypass lockdowns.
• Thresholds fire once. Each threshold fires exactly once per session. If the agent's budget is extended (e.g., by restarting with a new sentinel), thresholds will fire again.

Programmatic Usage

import { contextWarning } from "opencode-deadline-pressure";

// Called by OpenCode's plugin loader with (ctx, options)
// Returns a Hooks object

License

MIT