Skip to content

Commit f052aa0

Browse files
terisukeclaude
andcommitted
feat(guardrails): add multi-model delegation gates and quality/operational hooks
Delegation gates (OpenCode competitive advantage over Claude Code): - agent-model-mapping: tier-based model recommendation per agent type - delegation-budget-gate: hard block at 5 concurrent parallel tasks - cost-tracking: session-wide cost accumulation with threshold warning - parallel-execution-gate: prevents unbounded task delegation - verify-agent-output: detects empty/trivially short agent responses Quality hooks: - enforce-domain-naming: advisory for file naming convention mismatches - enforce-endpoint-dataflow: 4-point verification reminder on API changes - task-completion-gate: evidence verification before issue close - tool-failure-recovery: consecutive failure detection with recovery advice Operational hooks: - enforce-soak-time: merge timing advisory - enforce-follow-up-limit: feature freeze warning on 2+ consecutive fix PRs - enforce-issue-close-verification: acceptance criteria verification prompt - post-merge-close-issues: issue reference detection after merge - enforce-memory-update-on-commit: memory save reminder after significant edits - enforce-doc-update-scope: documentation freshness reminder guardrail.ts: 758 → 984 lines (+226) Refs #124, #125, #126 Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
1 parent 1cc9b02 commit f052aa0

1 file changed

Lines changed: 235 additions & 9 deletions

File tree

‎packages/guardrails/profile/plugins/guardrail.ts‎

Lines changed: 235 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -225,6 +225,45 @@ export default async function guardrail(input: {
225225
const state = path.join(root, "state.json")
226226
const allow: Record<string, Set<string>> = {}
227227

228+
// --- Delegation gate config ---
229+
const maxParallelTasks = 5
230+
const maxSessionCost = 10.0 // USD
231+
const agentModelTier: Record<string, "high" | "standard" | "low"> = {
232+
implement: "high",
233+
security: "high",
234+
"security-engineer": "high",
235+
"security-reviewer": "high",
236+
review: "standard",
237+
"code-reviewer": "standard",
238+
explore: "low",
239+
planner: "standard",
240+
architect: "high",
241+
"build-error-resolver": "standard",
242+
"tdd-guide": "standard",
243+
investigate: "low",
244+
"provider-eval": "low",
245+
"doc-updater": "low",
246+
"technical-writer": "low",
247+
"refactor-cleaner": "standard",
248+
"e2e-runner": "standard",
249+
}
250+
const tierModels: Record<string, string[]> = {
251+
high: ["glm-5.1", "glm-5", "gpt-5.4", "gpt-5.3-codex", "gpt-5.2-codex"],
252+
standard: ["glm-4.7", "glm-4.6", "gpt-5.2", "gpt-5.1-codex", "gpt-5.1-codex-mini"],
253+
low: ["glm-4.5-flash", "glm-4.5-air", "gpt-5-mini", "gpt-5-nano"],
254+
}
255+
256+
// --- Domain naming patterns ---
257+
const domainDirs: Record<string, RegExp> = {
258+
"src/ui/": /^[A-Z][a-zA-Z]*\.(tsx?|jsx?)$/,
259+
"src/components/": /^[A-Z][a-zA-Z]*\.(tsx?|jsx?)$/,
260+
"src/api/": /^[a-z][a-zA-Z]*\.(ts|js)$/,
261+
"src/routes/": /^[a-z][a-zA-Z-]*\.(ts|js)$/,
262+
"src/util/": /^[a-z][a-zA-Z-]*\.(ts|js)$/,
263+
"src/lib/": /^[a-z][a-zA-Z-]*\.(ts|js)$/,
264+
"test/": /\.(test|spec)\.(ts|tsx|js|jsx)$/,
265+
}
266+
228267
await mkdir(root, { recursive: true })
229268

230269
async function mark(data: Record<string, unknown>) {
@@ -414,6 +453,14 @@ export default async function guardrail(input: {
414453
last_reason: "",
415454
git_freshness_checked: false,
416455
review_state: "",
456+
// Delegation gates
457+
active_task_count: 0,
458+
session_cost: 0,
459+
consecutive_failures: 0,
460+
consecutive_fix_prs: 0,
461+
last_merge_at: "",
462+
issue_verification_done: false,
463+
edits_since_doc_reminder: 0,
417464
})
418465
}
419466
if (event.type === "permission.asked") {
@@ -559,11 +606,61 @@ export default async function guardrail(input: {
559606
} catch (e) { if (String(e).includes("blocked")) throw e }
560607
}
561608
}
609+
// Enforce soak time: develop→main merge requires half-day minimum
610+
if (/\b(git\s+merge|gh\s+pr\s+merge)\b/i.test(cmd)) {
611+
const data = await stash(state)
612+
const lastMerge = str(data.last_merge_at)
613+
if (lastMerge) {
614+
const elapsed = Date.now() - new Date(lastMerge).getTime()
615+
const halfDay = 12 * 60 * 60 * 1000
616+
if (elapsed < halfDay) {
617+
out.args.command = cmd // preserve command
618+
await seen("soak_time.advisory", { elapsed_ms: elapsed, required_ms: halfDay })
619+
// Advisory only — do not block, but warn via stderr injection
620+
}
621+
}
622+
}
623+
// Enforce follow-up limit: detect 2+ consecutive fix PRs on same feature
624+
if (/\bgh\s+pr\s+create\b/i.test(cmd)) {
625+
const data = await stash(state)
626+
const consecutiveFixes = num(data.consecutive_fix_prs)
627+
if (consecutiveFixes >= 2) {
628+
await seen("follow_up.limit_reached", { consecutive: consecutiveFixes })
629+
}
630+
}
631+
// Enforce issue close verification: require evidence before gh issue close
632+
if (/\bgh\s+issue\s+close\b/i.test(cmd)) {
633+
const data = await stash(state)
634+
if (!flag(data.issue_verification_done)) {
635+
await seen("issue_close.unverified", { command: cmd })
636+
}
637+
}
562638
if (!bash(cmd)) return
563639
if (!cfg.some((rule) => rule.test(file)) && !file.includes(".opencode/guardrails/")) return
564640
await mark({ last_block: "bash", last_command: cmd, last_reason: "protected runtime or config mutation" })
565641
throw new Error(text("protected runtime or config mutation"))
566642
}
643+
// Delegation: parallel execution gate for task tool
644+
if (item.tool === "task") {
645+
const data = await stash(state)
646+
const activeTasks = num(data.active_task_count)
647+
if (activeTasks >= maxParallelTasks) {
648+
const err = `parallel task limit reached (${activeTasks}/${maxParallelTasks}); wait for a running task to complete before delegating more`
649+
await mark({ last_block: "task", last_reason: err })
650+
throw new Error(text(err))
651+
}
652+
await mark({ active_task_count: activeTasks + 1 })
653+
}
654+
// Domain naming advisory for new file creation
655+
if (item.tool === "write" && file) {
656+
const relFile = rel(input.worktree, file)
657+
const fileName = path.basename(relFile)
658+
for (const [dir, pattern] of Object.entries(domainDirs)) {
659+
if (relFile.startsWith(dir) && !pattern.test(fileName)) {
660+
await seen("domain_naming.mismatch", { file: relFile, expected_pattern: pattern.source, dir })
661+
}
662+
}
663+
}
567664
},
568665
"tool.execute.after": async (
569666
item: { tool: string; args?: Record<string, unknown> },
@@ -681,6 +778,101 @@ export default async function guardrail(input: {
681778
edits_since_review: 0,
682779
})
683780
}
781+
// Delegation: decrement active task count on completion
782+
const activeTasks = num(data.active_task_count)
783+
if (activeTasks > 0) {
784+
await mark({ active_task_count: activeTasks - 1 })
785+
}
786+
// Delegation: track per-agent delegation count
787+
const agentDelegations = num(data[`delegation_${agent}`])
788+
await mark({ [`delegation_${agent}`]: agentDelegations + 1 })
789+
790+
// Verify agent output: detect empty or trivially short responses
791+
const output = str(out.output)
792+
if (agent && output.length < 20) {
793+
out.output = (out.output || "") + "\n⚠️ Agent output appears empty or trivially short. Verify the agent completed its task."
794+
await seen("verify_agent.short_output", { agent, output_length: output.length })
795+
}
796+
}
797+
798+
// Tool failure recovery: detect consecutive failures and suggest recovery
799+
if (out.output && /error|failed|exception/i.test(out.output) && !/⚠️|advisory/i.test(out.output)) {
800+
const failures = num(data.consecutive_failures) + 1
801+
await mark({ consecutive_failures: failures, last_failure_tool: item.tool })
802+
if (failures >= 3) {
803+
out.output = (out.output || "") + "\n⚠️ " + failures + " consecutive tool failures detected. Consider: (1) checking error root cause, (2) trying alternate approach, (3) delegating to a specialist agent."
804+
}
805+
} else if (item.tool !== "read") {
806+
// Reset failure counter on success (excluding reads)
807+
if (num(data.consecutive_failures) > 0) {
808+
await mark({ consecutive_failures: 0 })
809+
}
810+
}
811+
812+
// Post-merge: track merge timestamp for soak time and suggest issue close
813+
if (item.tool === "bash" && /\bgh\s+pr\s+merge\b/i.test(str(item.args?.command))) {
814+
await mark({ last_merge_at: now })
815+
const cmd = str(item.args?.command)
816+
// Check for "Fixes #N" or "Closes #N" patterns in recent context
817+
if (/\b(fix(es)?|close[sd]?|resolve[sd]?)\s+#\d+/i.test(out.output)) {
818+
out.output = (out.output || "") + "\n📋 Detected issue reference in merge output. Verify referenced issues are closed."
819+
}
820+
}
821+
822+
// Memory update reminder after git commit
823+
if (item.tool === "bash" && /\bgit\s+commit\b/i.test(str(item.args?.command))) {
824+
const editCount = num(data.edit_count)
825+
if (editCount >= 5) {
826+
out.output = (out.output || "") + "\n🧠 Significant changes committed (" + editCount + " edits). Consider updating memory with key decisions or learnings."
827+
}
828+
}
829+
830+
// Track fix PR creation for follow-up limit
831+
if (item.tool === "bash" && /\bgh\s+pr\s+create\b/i.test(str(item.args?.command))) {
832+
const cmd = str(item.args?.command)
833+
if (/--title\s+["']?fix/i.test(cmd) || /\bfix\//i.test(cmd)) {
834+
const consecutiveFixes = num(data.consecutive_fix_prs) + 1
835+
await mark({ consecutive_fix_prs: consecutiveFixes })
836+
if (consecutiveFixes >= 2) {
837+
out.output = (out.output || "") + "\n⚠️ Feature freeze warning: " + consecutiveFixes + " consecutive fix PRs on the same feature. Consider stabilizing before adding more changes."
838+
}
839+
} else {
840+
await mark({ consecutive_fix_prs: 0 })
841+
}
842+
}
843+
844+
// Endpoint dataflow advisory: detect API endpoint modifications
845+
if ((item.tool === "edit" || item.tool === "write") && file && code(file)) {
846+
const relFile = rel(input.worktree, file)
847+
const content = typeof item.args?.content === "string" ? item.args.content :
848+
typeof item.args?.newString === "string" ? item.args.newString : ""
849+
if (content && /\b(router\.(get|post|put|patch|delete)|app\.(get|post|put|patch|delete)|fetch\(|axios\.|\.handler)\b/i.test(content)) {
850+
out.output = (out.output || "") + "\n🔄 Endpoint modification detected in " + relFile + ". Verify 4-point dataflow: client → API route → backend action → response format."
851+
await seen("endpoint_dataflow.modified", { file: relFile })
852+
}
853+
}
854+
855+
// Doc update scope: remind about related documentation when modifying source
856+
if ((item.tool === "edit" || item.tool === "write") && file && code(file)) {
857+
const relFile = rel(input.worktree, file)
858+
const editsSinceDocCheck = num(data.edits_since_doc_reminder)
859+
if (editsSinceDocCheck >= 5) {
860+
out.output = (out.output || "") + "\n📄 " + (editsSinceDocCheck + 1) + " source edits since last doc check. Grep for references to modified files in docs/ and README."
861+
await mark({ edits_since_doc_reminder: 0 })
862+
} else {
863+
await mark({ edits_since_doc_reminder: editsSinceDocCheck + 1 })
864+
}
865+
}
866+
867+
// Task completion gate: ensure task claims are backed by evidence
868+
if (item.tool === "bash" && /\b(gh\s+issue\s+close)\b/i.test(str(item.args?.command))) {
869+
const reviewed = flag(data.reviewed)
870+
const factchecked = flag(data.factchecked)
871+
if (!reviewed || !factchecked) {
872+
out.output = (out.output || "") + "\n⚠️ Issue close without full verification: reviewed=" + reviewed + ", factchecked=" + factchecked + ". Ensure acceptance criteria have code-level evidence."
873+
await seen("task_completion.incomplete", { reviewed, factchecked })
874+
}
875+
await mark({ issue_verification_done: true })
684876
}
685877
},
686878
"command.execute.before": async (
@@ -725,16 +917,47 @@ export default async function guardrail(input: {
725917
options: Record<string, unknown>
726918
},
727919
) => {
920+
// Provider admission gate (existing)
728921
const err = gate(item)
729-
if (!err) return
730-
await mark({
731-
last_block: "chat.params",
732-
last_provider: item.model.providerID,
733-
last_model: item.model.id,
734-
last_agent: item.agent,
735-
last_reason: err,
736-
})
737-
throw new Error(text(err))
922+
if (err) {
923+
await mark({
924+
last_block: "chat.params",
925+
last_provider: item.model.providerID,
926+
last_model: item.model.id,
927+
last_agent: item.agent,
928+
last_reason: err,
929+
})
930+
throw new Error(text(err))
931+
}
932+
933+
// Agent-model mapping advisory: suggest optimal model tier for agent
934+
const tier = agentModelTier[item.agent]
935+
if (tier) {
936+
const recommended = tierModels[tier] ?? []
937+
const modelId = str(item.model.id)
938+
if (recommended.length > 0 && modelId) {
939+
const currentTier = Object.entries(tierModels).find(([, models]) => models.includes(modelId))?.[0]
940+
if (currentTier && tier === "high" && currentTier === "low") {
941+
await seen("delegation.model_mismatch", {
942+
agent: item.agent,
943+
expected_tier: tier,
944+
actual_tier: currentTier,
945+
model: modelId,
946+
})
947+
}
948+
}
949+
}
950+
951+
// Cost tracking: accumulate per-session cost
952+
const data = await stash(state)
953+
const sessionCost = num(data.session_cost)
954+
const modelCost = (item.model.cost?.input ?? 0) + (item.model.cost?.output ?? 0)
955+
if (modelCost > 0) {
956+
await mark({ session_cost: sessionCost + modelCost })
957+
}
958+
if (sessionCost > maxSessionCost) {
959+
await seen("delegation.cost_warning", { session_cost: sessionCost, max: maxSessionCost })
960+
}
738961
},
739962
"experimental.session.compacting": async (
740963
_item: { sessionID: string },
@@ -751,6 +974,9 @@ export default async function guardrail(input: {
751974
`Edit/write count: ${num(data.edit_count)}.`,
752975
`Fact-check state: ${factLine(data)}.`,
753976
`Review state: ${reviewLine(data)}.`,
977+
`Active tasks: ${num(data.active_task_count)}.`,
978+
`Session cost: $${num(data.session_cost).toFixed(4)}.`,
979+
`Consecutive failures: ${num(data.consecutive_failures)}.`,
754980
].join(" "),
755981
)
756982
},

0 commit comments

Comments
 (0)