carthagent 0.0.0-stage → 1.0.7

package/plugins/carthagent/src/server/codegraph.ts

@@ -0,0 +1,46 @@
+import { createCodeIndex } from "../../../../lib/codegraph.mjs"
+import { boundedCodeNavResult } from "../../../../lib/codegraph-query.mjs"
+import { resolve } from "node:path"
+import type { Context } from "@opencode/plugin/promise/plugin"
+import type { Tool } from "@opencode/schema/tool"
+
+type CodeNavInput = { op: string; name?: string; path?: string; container?: string; limit?: number; offset?: number }
+
+const schema = {
+  type: "object", additionalProperties: false, required: ["op"],
+  properties: {
+    op: { type: "string", enum: ["definition", "symbols", "callers", "callees", "imports", "importers", "outline", "status"] },
+    name: { type: "string" }, path: { type: "string" }, container: { type: "string" },
+    limit: { type: "integer", minimum: 1, maximum: 200, default: 50 }, offset: { type: "integer", minimum: 0, default: 0 },
+  },
+}
+const result = (value: string) => ({ content: value })
+
+/** Register the structural navigator in the OpenCode server tool registry. */
+export async function registerCodegraph(ctx: Context, options: { maxFiles?: number } = {}) {
+  const indexes = new Map<string, Promise<Awaited<ReturnType<typeof createCodeIndex>>>>()
+  const registration = await ctx.tool.transform(editor => {
+    editor.namespace?.({ name: "carthagent", description: "Carthagent code navigation" })
+    editor.add({
+      name: "code_nav", description: "Read-only structural graph for JS/TS/Python/Rust. Use definition/symbols/outline to locate code and callers/importers before changing APIs. Calls are name-based candidates, not resolved bindings. Results include coverage, total and nextOffset; page or filter incomplete answers.",
+      input: schema as Tool.ValueSchema<CodeNavInput>, options: { namespace: "carthagent", codemode: true, permission: "carthagent_code_nav" },
+      execute: async (rawInput, toolContext) => {
+        const input = rawInput as CodeNavInput
+        const session = await ctx.session.get({ sessionID: toolContext.sessionID })
+        const root = resolve(session.location.directory, session.subpath || ".")
+        let index = indexes.get(root)
+        if (!index) {
+          const maxFiles = options.maxFiles ?? 8000
+          if (!Number.isSafeInteger(maxFiles) || maxFiles < 1) throw Error("codegraph maxFiles must be a positive safe integer")
+          index = createCodeIndex(root, { maxFiles })
+          index.catch(() => indexes.delete(root))
+          indexes.set(root, index)
+        }
+        const current = await index
+        await current.refresh()
+        return result(boundedCodeNavResult(current, input))
+      },
+    })
+  })
+  return () => { indexes.clear(); return registration.dispose() }
+}

package/plugins/carthagent/src/server/delivery.ts

@@ -0,0 +1,488 @@
+import { randomUUID } from "node:crypto"
+import type { Context } from "@opencode/plugin/promise/plugin"
+import type { ToolContext } from "@opencode/plugin/promise/tool"
+import type { Tool } from "@opencode/schema/tool"
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs"
+import { basename, join, resolve } from "node:path"
+import { DELIVERY_INVARIANTS, TEST_INFRASTRUCTURE_GUIDANCE, deliveryPhaseGuidance } from "../../../../lib/delivery-guidance.mjs"
+import { deliveryRecovery, designReceipt, recoveryMessages } from "../../../../lib/delivery-context.mjs"
+import { validatePlanning, inspectPlanning, recordPlanReview, approvePlanning, planningStatus, startImplementation } from "../../../../lib/planning.mjs"
+import { PLANNING_START, planningGuide, planningNext } from "../../../../lib/planning-guide.mjs"
+import { newDiscovery, restoreDiscovery, discoveryCheckpoint, discoveryEvent } from "../../../../lib/planning-discovery.mjs"
+import { budgetLimits, newBudget, budgetReason, budgetSnapshot } from "../../../../lib/budget.mjs"
+import { validatePlan, fingerprint, runCommand, pendingChecks, validateRevision, bindRequiredChecks, loadRequiredChecks, updateStepStatus, verificationMode, looksInformational, revisePlan, mergePlanPatch, completionIssues, planSteps, pendingRequirements, planD2WithProgress, evidenceIdentity } from "../../../../lib/delivery.mjs"
+import { captureDeliveryReview, recordDeliveryReview } from "../../../../lib/delivery-review.mjs"
+import { formatGuidance, loadGuidanceProfiles, routeGuidance } from "../../../../lib/guidance.mjs"
+import { saveReport, reconcileReport } from "../../../../lib/reports.mjs"
+import { lockWorkspace, selectReport, assertActiveReport } from "../../../../lib/workspace.mjs"
+import { enforceToolPolicy, policyDescription } from "./policy.ts"
+import { effectiveSessionOptions } from "../../../../lib/opencode/session-options.mjs"
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- Existing workflow snapshots mirror evolving JS domain schemas. */
+type SessionState = { state: any; discovery: any; nudges: number; touched: boolean; budget: any; required: any[]; configError?: string; extraGuidance?: string; initialFiles: string[]; lastPrompt?: string; guidance?: string; writeCounts?: Record<string, number>; outcome?: string; cwd?: string }
+type DeliveryOptions = Record<string, unknown>
+type Schema = Record<string, unknown>
+type DeliveryInput = Record<string, any>
+type RegisteredToolContext = ToolContext
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+const S = (description?: string) => ({ type: "string", minLength: 1, maxLength: 1200, ...(description ? { description } : {}) })
+const A = (items: Schema, maxItems = 20): Schema => ({ type: "array", items, maxItems })
+const O = (properties: Record<string, Schema>, required = Object.keys(properties)): Schema => ({ type: "object", properties, required, additionalProperties: false })
+const text = (value: unknown) => ({ content: typeof value === "string" ? value : JSON.stringify(value, null, 2) })
+const empty = O({}, [])
+const short = S()
+const steps = A({ anyOf: [short, O({ id: { type: "string", pattern: "^[a-z][a-z0-9_-]{0,39}$" }, title: short, kind: { type: "string", enum: ["work", "regression"] }, dependsOn: A(short, 40), checks: A(short, 24) }, ["id", "title"])] }, 40)
+const checks = A(O({ id: { type: "string", pattern: "^[a-z][a-z0-9_-]{0,39}$" }, kind: { type: "string", enum: ["test", "runtime", "static"] }, argv: A(short, 80), timeoutSeconds: { type: "integer", minimum: 1, maximum: 300 } }), 24)
+const acceptance = A(O({ requirement: short, checks: A(short, 24) }), 40)
+const planSchema = O({ goal: short, assumptions: A(short), artifacts: A(short, 40), outputs: A(short, 40), steps, verification: { type: "string", enum: ["required", "advisory", "none"] }, acceptance, checks, design: { type: "object", additionalProperties: true }, workflow: { type: "object", additionalProperties: true }, outcomes: A({ type: "object", additionalProperties: true }, 32) }, ["goal", "assumptions", "artifacts", "steps", "acceptance", "checks"])
+
+function sessionKey(sessionID: string) { return `session/${sessionID}` }
+
+/**
+ * Register CTG delivery tools and server hooks against OpenCode V2's Promise plugin context.
+ * Call from Plugin.define({ setup(ctx) { return registerDelivery(ctx, options) } }).
+ * Every operation derives both sessionID and worktree directory from the invocation/session API;
+ * no active-session process global is used. State is durable per session in ctx.storage while
+ * the existing .harness report and workspace lock remain canonical cross-process coordination.
+ */
+export async function registerDelivery(ctx: Context, options: DeliveryOptions = {}) {
+  const registrations: Array<{ dispose(): Promise<void> }> = []
+  const serial = new Map<string, Promise<unknown>>()
+  const budgetTimers = new Map<string, ReturnType<typeof setTimeout>>()
+  const admittedCalls = new Set<string>()
+  const profiles = loadGuidanceProfiles()
+  let disposed = false
+  const limitOptions: Record<string, string> = { "delivery-max-tools": "maxTools", "delivery-max-seconds": "maxSeconds", "delivery-max-repairs": "maxRepairs" }
+  const sessionOptions = (session: Parameters<typeof effectiveSessionOptions>[0]): Record<string, unknown> => effectiveSessionOptions(session, { ...ctx.options, ...options })
+  async function scope(sessionID: string) {
+    if (!sessionID) throw Error("OpenCode sessionID is required")
+    const session = await ctx.session.get({ sessionID })
+    const cwd = session.location?.directory
+    if (typeof cwd !== "string" || !cwd) throw Error(`OpenCode session ${sessionID} has no worktree location`)
+    const opts = sessionOptions(session)
+    const saved = await ctx.storage.get(sessionKey(sessionID)) as SessionState | undefined
+    const data: SessionState = saved ? structuredClone(saved) : { state: null, discovery: newDiscovery(), nudges: 0, touched: false, budget: null, required: [], initialFiles: [] }
+    data.cwd = cwd
+    data.outcome = session.outcome
+    data.discovery = restoreDiscovery(data.discovery)
+    if (data.state) {
+      const dir = runDirectory(cwd, sessionID, data.state.runId)
+      data.state = reconcileReport(join(dir, "report.json"), data.state)
+    }
+    const limits = budgetLimits((name: string) => opts[limitOptions[name]] ?? opts[name] ?? "0")
+    if (!data.budget) data.budget = newBudget(limits)
+    else if (JSON.stringify(data.budget.limits) !== JSON.stringify(limits)) data.budget.limits = limits
+    if (data.budget.limits.seconds && !budgetTimers.has(sessionID) && !data.budget.stopped) {
+      const remaining = Math.max(1, data.budget.startedAt + data.budget.limits.seconds * 1000 - Date.now())
+      const timer = setTimeout(() => {
+        void serialized(sessionID, async () => {
+          const latest = await scope(sessionID)
+          if (!latest.data.budget.stopped) {
+            latest.data.budget.stopped = "elapsed-time"
+            await ctx.storage.set(sessionKey(sessionID), latest.data)
+            await ctx.session.interrupt({ sessionID, resume: false })
+          }
+        }).catch(error => console.error("Carthagent delivery budget stop failed", error))
+      }, remaining)
+      timer.unref?.(); budgetTimers.set(sessionID, timer)
+    }
+    if (!data.required.length) {
+      const explicit = typeof opts.validators === "string" ? opts.validators : undefined
+      const projectManifest = join(cwd, ".carthagent", "delivery.json")
+      const manifest = explicit ? resolve(cwd, explicit) : existsSync(projectManifest) ? projectManifest : undefined
+      try { if (manifest) data.required = loadRequiredChecks(manifest, cwd) }
+      catch (error) { data.configError = `Invalid required validators: ${error}` }
+      if (typeof opts.context === "string") {
+        try { data.extraGuidance = readFileSync(resolve(cwd, opts.context), "utf8") }
+        catch (error) { data.configError = `Invalid delivery context: ${error}` }
+      }
+      if (opts.protectExisting) data.initialFiles = readdirSync(cwd, { withFileTypes: true }).filter(e => e.isFile()).map(e => resolve(cwd, e.name))
+    }
+    if (data.state && data.required.length) {
+      for (const check of data.required) {
+        const old = data.state.plan.checks.find((c: { id: string }) => c.id === check.id)
+        if (JSON.stringify(old) !== JSON.stringify(check)) delete data.state.evidence[check.id]
+      }
+      data.state.plan = bindRequiredChecks(data.state.plan, data.required)
+    }
+    return { session, cwd, data, options: opts }
+  }
+  function runDirectory(cwd: string, sessionID: string, runId: string) { return join(cwd, ".harness", sessionID, runId) }
+  async function persist(cwd: string, sessionID: string, data: SessionState) {
+    if (data.state) {
+      const dir = runDirectory(cwd, sessionID, data.state.runId)
+      mkdirSync(dir, { recursive: true })
+      saveReport(join(dir, "report.json"), data.state)
+      selectReport(cwd, join(dir, "report.json"))
+    }
+    await ctx.storage.set(sessionKey(sessionID), data)
+  }
+  async function serialized<T>(sessionID: string, job: () => Promise<T>): Promise<T> {
+    const previous = serial.get(sessionID) || Promise.resolve()
+    const current = previous.then(job)
+    serial.set(sessionID, current.catch(() => {}))
+    return current
+  }
+  async function operate<T>(sessionID: string, job: (s: Awaited<ReturnType<typeof scope>>) => Promise<T>, replace = false): Promise<T> {
+    return serialized(sessionID, async () => {
+      const s = await scope(sessionID)
+      const release = lockWorkspace(s.cwd)
+      try {
+        if (!replace && s.data.state) {
+          const dir = runDirectory(s.cwd, sessionID, s.data.state.runId)
+          assertActiveReport(s.cwd, join(dir, "report.json"))
+          s.data.state = reconcileReport(join(dir, "report.json"), s.data.state)
+        }
+        return await job(s)
+      } finally { release() }
+    })
+  }
+  const add = (editor: Parameters<Parameters<Context["tool"]["transform"]>[0]>[0], name: string, description: string, input: Schema, execute: (input: DeliveryInput, toolContext: RegisteredToolContext) => Promise<{ content: string }>) => editor.add({
+    name, description, input: input as Tool.ValueSchema<DeliveryInput>, execute: async (rawValue, tool) => {
+      const value = rawValue as DeliveryInput
+      const { options: opts } = await scope(tool.sessionID)
+      if (!opts.delivery) throw Error("Carthagent delivery tools are disabled for this session.")
+      return execute(value, tool)
+    }, options: { namespace: "carthagent", codemode: true },
+  })
+
+  registrations.push(await ctx.tool.transform(editor => {
+    editor.namespace?.({ name: "carthagent", description: "Evidence-driven CTG delivery workflow tools" })
+    add(editor, "delivery_plan", "Create the durable acceptance contract and plan.d2. Informational asks may use verification none/advisory; product changes require fresh checks.", planSchema, async (input, tool) => operate(tool.sessionID, async ({ cwd, data, options: opts }) => {
+      if (data.configError) throw Error(data.configError)
+      const plan = validatePlan(bindRequiredChecks({ ...input, verification: input.verification ?? "required" }, data.required), cwd)
+      validateRevision(data.state, plan)
+      if (data.state && !["verified", "blocked"].includes(data.state.status)) data.state = revisePlan(data.state, plan, { cwd, hash: fingerprint(cwd, ["."]), reason: "Active plan replaced via delivery_plan" })
+      else data.state = { version: 1, workflowMode: opts.workflow === "strict" ? "strict" : "standard", reviewRequired: opts.workflow !== "strict", runId: randomUUID(), revision: (data.state?.revision || 0) + 1, plan, evidence: {}, status: "implementing", createdAt: new Date().toISOString(), stepStatus: {} }
+      data.discovery = newDiscovery(); const dir = runDirectory(cwd, tool.sessionID, data.state.runId)
+      mkdirSync(dir, { recursive: true }); writeFileSync(join(dir, "plan.d2"), planD2WithProgress(data.state.plan, data.state.stepStatus))
+      await persist(cwd, tool.sessionID, data)
+      return text({ plan: join(dir, "plan.d2"), report: join(dir, "report.json"), next: data.state.workflowMode === "standard" ? "Contract accepted; implement, verify all checks, review and finish." : "No code or commands yet. Validate, inspect, adversarially review, then approve the design." })
+    }, true))
+    add(editor, "delivery_probe", "Bounded pre-plan version probe only; other APIs can be inspected with read.", O({ kind: { type: "string", enum: ["node-version", "npm-version"] } }), async (input, tool) => {
+      const { cwd } = await scope(tool.sessionID)
+      const argv = input.kind === "node-version" ? [process.execPath, "--version"] : [process.platform === "win32" ? "npm.cmd" : "npm", "--version"]
+      return text({ ...(await runCommand(argv, { cwd, signal: tool.signal, timeoutSeconds: 10 } as Parameters<typeof runCommand>[1])), evidence: false })
+    })
+    add(editor, "delivery_revise", "Revise the current task with a reason and partial patch. Existing obligations and verification history cannot be removed.", O({ reason: short, patch: { type: "object", additionalProperties: true } }), async (input, tool) => operate(tool.sessionID, async ({ cwd, data }) => {
+      if (!data.state) throw Error("Call delivery_plan first")
+      const hash = fingerprint(cwd, ["."])
+      data.state = revisePlan(data.state, bindRequiredChecks(mergePlanPatch(data.state.plan, input.patch), data.required), { cwd, reason: input.reason, hash })
+      await persist(cwd, tool.sessionID, data)
+      return text({ revision: data.state.revision, pendingChecks: pendingChecks(data.state, hash), unverifiedRequirements: pendingRequirements(data.state, hash), next: data.state.workflowMode === "standard" ? "Continue implementation; changed checks require fresh evidence." : "Revision relocks implementation; validate and re-approve." })
+    }))
+    add(editor, "delivery_design", "Strict workflow design gate. Guide, validate, inspect, adversarially review every scenario, then approve. Review is model-authored, not independent proof.", O({ action: { type: "string", enum: ["guide", "validate", "inspect", "review", "approve"] }, captureId: short, review: { type: "object", additionalProperties: true } }, ["action"]), async (input, tool) => {
+      if (input.action === "guide") return text(planningGuide())
+      return operate(tool.sessionID, async ({ cwd, data }) => {
+        if (!data.state) throw Error("Call delivery_plan first")
+        const hash = fingerprint(cwd, ["."]); let result
+        if (input.action === "validate") result = validatePlanning(data.state, hash)
+        else if (input.action === "inspect") result = inspectPlanning(data.state, hash)
+        else if (input.action === "review") result = recordPlanReview(data.state, hash, { ...input.review, captureId: input.review?.captureId ?? input.captureId })
+        else if (input.action === "approve") result = approvePlanning(data.state, hash)
+        else throw Error("Unknown delivery_design action")
+        await persist(cwd, tool.sessionID, data)
+        return text({ result: designReceipt(input.action, result), ...(input.action === "inspect" ? { captureId: result.id } : {}), ...(input.action === "validate" ? planningNext(data.state, result) : {}), planningStatus: planningStatus(data.state, hash) })
+      })
+    })
+    add(editor, "delivery_status", "Show delivery state, stale/failed checks and next action. Call finish instead of polling when readyToFinish is true.", empty, async (_input, tool) => operate(tool.sessionID, async ({ cwd, data }) => {
+      if (!data.state) return text("No delivery contract.")
+      const dir = runDirectory(cwd, tool.sessionID, data.state.runId); const hash = fingerprint(cwd, ["."])
+      const issues = completionIssues(data.state, cwd, hash); const readyToFinish = Object.values(issues).every(items => !items.length)
+      return text({ ...deliveryRecovery(data.state, { report: join(dir, "report.json") }), pendingChecks: pendingChecks(data.state, hash), completionIssues: issues, readyToFinish, next: readyToFinish ? "Call delivery_finish; do not poll again." : "Run declared checks, complete steps/outputs, and resolve outstanding requirements." })
+    }))
+    add(editor, "delivery_progress", "Update implementation step progress and regenerate the plan diagram.", O({ step: { anyOf: [{ type: "integer", minimum: 0 }, short] }, status: { type: "string", enum: ["active", "done", "failed", "pending"] }, note: short }, ["step", "status"]), async (input, tool) => operate(tool.sessionID, async ({ cwd, data }) => {
+      if (!data.state) throw Error("Call delivery_plan first")
+      const step = planSteps(data.state.plan).find((s: { id: string }, i: number) => typeof input.step === "string" ? s.id === input.step : i === input.step)
+      const hash = input.status === "done" && step?.checks.length ? fingerprint(cwd, ["."]) : undefined
+      updateStepStatus(data.state, input.step, input.status, hash)
+      if (input.note) data.state.progressNotes = [...(data.state.progressNotes || []), { step: step?.id, status: input.status, note: input.note, revision: data.state.revision, at: new Date().toISOString() }]
+      const dir = runDirectory(cwd, tool.sessionID, data.state.runId); writeFileSync(join(dir, "plan.d2"), planD2WithProgress(data.state.plan, data.state.stepStatus)); await persist(cwd, tool.sessionID, data)
+      return text({ step: input.step, status: input.status, plan: join(dir, "plan.d2") })
+    }))
+    add(editor, "delivery_check", "Run declared check(s) with no implicit shell, deadline, full logs and current workspace fingerprint. Checks never fabricate evidence.", O({ id: short }), async (input, tool) => operate(tool.sessionID, async ({ cwd, data }) => {
+      if (!data.state) throw Error("Call delivery_plan first")
+      const verification = verificationMode(data.state.plan)
+      if (verification === "none") return text({ verification, note: "No checks are declared for this informational plan; call delivery_finish." })
+      startImplementation(data.state, fingerprint(cwd, ["."]))
+      const selected = input.id === "all" ? data.state.plan.checks : data.state.plan.checks.filter((c: { id: string }) => c.id === input.id)
+      if (!selected.length) throw Error("Unknown check ID; use delivery_status or id=all")
+      const results = []
+      for (const check of selected) {
+        if (tool.signal.aborted) throw Error("Check cancelled before execution")
+        const identity = evidenceIdentity(data.state, check); data.state.status = "verifying"; data.state.verificationStarted = true; delete data.state.evidence[check.id]
+        const before = fingerprint(cwd, ["."]); await persist(cwd, tool.sessionID, data)
+        const dir = runDirectory(cwd, tool.sessionID, data.state.runId)
+        const result = await runCommand(check.argv, { cwd, timeoutSeconds: check.timeoutSeconds, signal: tool.signal, logPath: join(dir, `${check.id}-${randomUUID()}.log`) } as Parameters<typeof runCommand>[1])
+        const after = fingerprint(cwd, ["."]); const passed = result.code === 0 && !result.timedOut && !result.cancelled && !result.outputLimit && before === after
+        data.state.evidence[check.id] = { passed, ...identity, executedRevision: data.state.revision, fingerprint: after, code: result.code, timedOut: result.timedOut, cancelled: result.cancelled, logPath: result.logPath, durationMs: result.durationMs, changedDuringCheck: before !== after, outputTail: result.output.slice(-1200) }
+        results.push({ id: check.id, advisory: verification !== "required", ...data.state.evidence[check.id], outputTail: result.output })
+        await persist(cwd, tool.sessionID, data)
+      }
+      const failures = results.filter(r => !r.passed && verification === "required")
+      if (failures.length) throw Error(JSON.stringify({ failures, next: "Repair actual failures; do not weaken obligations." }))
+      const hash = fingerprint(cwd, ["."]); const issues = completionIssues(data.state, cwd, hash)
+      return text({ results, pendingChecks: pendingChecks(data.state, hash), completionIssues: issues, readyToFinish: Object.values(issues).every(items => !items.length) })
+    }))
+    add(editor, "delivery_review", "Inspect final diff or record assertion coverage, boundary probes and findings. Required for structured plans; assertions are model-authored.", O({ action: { type: "string", enum: ["inspect", "record"] }, captureId: short, coverage: A({ type: "object", additionalProperties: true }, 64), resolutions: A({ type: "object", additionalProperties: true }, 40), outcomes: A({ type: "object", additionalProperties: true }, 32), probes: A(short, 40), findings: A(short, 40), limitations: A(short) }, ["action"]), async (input, tool) => operate(tool.sessionID, async ({ cwd, data }) => {
+      if (!data.state) throw Error("Call delivery_plan first")
+      const result = input.action === "inspect" ? await captureDeliveryReview(data.state, cwd, runDirectory(cwd, tool.sessionID, data.state.runId), tool.signal) : input.action === "record" ? recordDeliveryReview(data.state, cwd, input) : (() => { throw Error("Review action must be inspect or record") })()
+      await persist(cwd, tool.sessionID, data); return text(result)
+    }))
+    add(editor, "delivery_finish", "Finish delivery. Verified requires every required validator, fresh check, output, step, requirement and review gate; blocked requires specific limitations.", O({ status: { type: "string", enum: ["verified", "blocked"] }, review: short, launch: short, limitations: A(short) }), async (input, tool) => operate(tool.sessionID, async ({ cwd, data }) => {
+      if (!data.state) throw Error("Call delivery_plan first")
+      if (data.configError) throw Error(data.configError)
+      const verification = verificationMode(data.state.plan); let hash: string | null = null
+      if (input.status === "verified") {
+        hash = fingerprint(cwd, ["."])
+        if (verification === "required") {
+          const issues = completionIssues(data.state, cwd, hash)
+          if (Object.values(issues).some(items => items.length)) throw Error(`Cannot verify: ${JSON.stringify(issues)}`)
+        }
+      } else {
+        if (!input.limitations.length) throw Error("Blocked delivery requires an explicit limitation/reason")
+        try { hash = fingerprint(cwd, ["."]) } catch { hash = "unfingerprinted:scope_exceeded" }
+      }
+      data.state.status = input.status; data.state.handoff = { ...input, verification, advisory: verification !== "required", fingerprint: hash, at: new Date().toISOString(), evidence: structuredClone(data.state.evidence), reviewEvidence: data.state.reviewEvidence || null }
+      await persist(cwd, tool.sessionID, data); return text({ status: data.state.status, verification, report: join(runDirectory(cwd, tool.sessionID, data.state.runId), "report.json") })
+    }))
+  }))
+
+  registrations.push(await ctx.tool.hook("execute.before", async event => serialized(event.sessionID, async () => {
+    if (typeof event.id !== "string" || !event.id) throw Error("Tool execution locked: host did not provide an authoritative call ID.")
+    if (typeof event.messageID !== "string" || !event.messageID) throw Error("Tool execution locked: host did not provide an authoritative message ID.")
+    // Include tool name because Code Mode's dispatcher and its nested tools can
+    // share the outer call ID/message ID while still being distinct invocations.
+    const callKey = `${event.sessionID}\0${event.messageID}\0${event.id}\0${event.tool}`
+    if (admittedCalls.has(callKey)) return
+    const { cwd, data, options: opts } = await scope(event.sessionID)
+    if (!opts.delivery && Number(data.budget.limits.tools) === 0 && Number(data.budget.limits.seconds) === 0 && Number(data.budget.limits.repairs) === 0) return
+    let persistenceAttempted = false
+    try {
+      const nativeShell = ["bash", "shell", "powershell"].includes(event.tool)
+      const input = event.input && typeof event.input === "object" ? event.input as Record<string, unknown> : {}
+      if (opts.delivery && event.tool !== "execute" && requiresImplementationTool(event.tool)) {
+        if (!data.state) throw Error(`Implementation locked: call delivery_plan first (tool ${event.tool}).`)
+        const release = lockWorkspace(cwd)
+        try {
+          const dir = runDirectory(cwd, event.sessionID, data.state.runId)
+          assertActiveReport(cwd, join(dir, "report.json"))
+          data.state = reconcileReport(join(dir, "report.json"), data.state)
+          enforceToolPolicy(event.tool, data.state, cwd)
+          await persist(cwd, event.sessionID, data)
+        } finally { release() }
+      }
+      if ((event.tool === "write" || event.tool === "edit") && typeof input.path === "string") {
+        const path = input.path.replaceAll("\\", "/"), cwdPath = cwd.replaceAll("\\", "/").replace(/^\/+/, ""), name = basename(cwd)
+        if ([cwdPath, name].some(prefix => path === prefix || path.startsWith(`${prefix}/`))) throw Error("Path recreates working directory inside itself; use a workspace-relative product path.")
+        if (event.tool === "write" && data.initialFiles.includes(resolve(cwd, input.path))) throw Error(`Preserve existing ${input.path}; use focused edits.`)
+      }
+      const cap = Number(opts.bashCap) || 0
+      if (nativeShell) {
+        const command = String(input.command ?? "")
+        if (/\b(?:pkill|killall)\b|\bkill\s+(?:-\S+\s+)*(?:-1|0)(?:\s|$)/i.test(command)) throw Error("Broad process termination is prohibited; terminate only a captured child PID.")
+        if (cap > 0 && (typeof input.timeout !== "number" || input.timeout > cap)) input.timeout = cap
+      }
+      if (["write", "edit", "patch"].includes(event.tool) && opts.rewriteCap && Number(opts.rewriteCap) > 0) {
+        data.writeCounts ||= {}
+        const path = String(input.path || "")
+        const count = data.writeCounts[path] || 0
+        if (count >= Number(opts.rewriteCap)) throw Error(`Full-file rewrite limit reached for ${path}; preserve behavior and use focused edits.`)
+        data.writeCounts[path] = count + 1
+      }
+      // execute.before is the authoritative per-invocation boundary, including
+      // native shell, plugin tools, subagent dispatch, and Code Mode calls. It
+      // carries sessionID/call ID; shell.create.before does not.
+      if (!admittedCalls.has(callKey)) {
+        const reason = budgetReason(data.budget, "tool")
+        if (reason) {
+          data.budget.stopped ||= reason
+          persistenceAttempted = true
+          await ctx.storage.set(sessionKey(event.sessionID), data)
+          await ctx.session.interrupt({ sessionID: event.sessionID, resume: false })
+          throw Error(`Delivery budget exhausted: ${reason}. Explicit delivery-budget-reset required.`)
+        }
+        data.budget.tools++
+      }
+      persistenceAttempted = true
+      await ctx.storage.set(sessionKey(event.sessionID), data)
+      admittedCalls.add(callKey)
+    } catch (error) {
+      // A policy rejection means no tool executes. Persist the observed state but
+      // never leave a provisional shell claim behind for a later user command.
+      if (!persistenceAttempted) await ctx.storage.set(sessionKey(event.sessionID), data)
+      throw error
+    }
+  })))
+
+  registrations.push(await ctx.tool.hook("execute.after", async event => serialized(event.sessionID, async () => {
+    const { cwd, data } = await scope(event.sessionID)
+    if (!sessionOptions(await ctx.session.get({ sessionID: event.sessionID })).delivery) {
+      await ctx.storage.set(sessionKey(event.sessionID), data)
+      return
+    }
+    const failed = event.status === "error"
+    if (!failed && ["write", "edit"].includes(event.tool)) data.touched = true
+    if (data.discovery.active && ["read", "ls", "find", "grep", "code_nav"].includes(event.tool)) data.discovery = discoveryEvent(data.discovery, "read")
+    if (data.state && ["delivery_check", "delivery_progress", "delivery_review", "delivery_finish", "delivery_revise", "delivery_design", "delivery_plan"].includes(event.tool)) {
+      const dir = runDirectory(cwd, event.sessionID, data.state.runId)
+      if (existsSync(join(dir, "report.json"))) data.state = reconcileReport(join(dir, "report.json"), data.state)
+    }
+    const { options: opts } = await scope(event.sessionID)
+    const outputCap = Math.max(0, Number(opts.toolOutputCap) || 0)
+    if (!failed && outputCap > 0 && event.result?.content) {
+      if (!Array.isArray(event.result.content)) {
+        await ctx.storage.set(sessionKey(event.sessionID), data)
+        return
+      }
+      const content = event.result.content.map(item => {
+        if (item.type !== "text" || item.text.length <= outputCap) return item
+        const marker = `\n...[${item.text.length - outputCap} chars omitted; rerun a narrower command]...\n`
+        const head = Math.floor(Math.max(0, outputCap - marker.length) / 3)
+        const tail = Math.max(0, outputCap - marker.length - head)
+        return { ...item, text: outputCap <= marker.length ? item.text.slice(0, outputCap) : item.text.slice(0, head) + marker + item.text.slice(-tail) }
+      })
+      event.result = { ...event.result, content }
+    }
+    await ctx.storage.set(sessionKey(event.sessionID), data)
+  })))
+
+  registrations.push(await ctx.shell.hook("create.before", async event => {
+    // Session-scoped policy, limits, and budget were handled at execute.before.
+    // This hook intentionally does not attribute commands: 2.0.32 has no
+    // authoritative source.sessionID/callID on ShellCreateBefore.
+    const cap = Number(options.bashCap) || 0
+    if (cap > 0 && event.timeout > cap) event.timeout = cap
+    if (/\b(?:pkill|killall)\b|\bkill\s+(?:-\S+\s+)*(?:-1|0)(?:\s|$)/i.test(event.command)) throw Error("Broad process termination is prohibited; terminate only a captured child PID.")
+  }))
+
+  for (const kind of ["context", "compaction"] as const) registrations.push(await ctx.session.hook(kind, async event => {
+    const { cwd, data } = await scope(event.sessionID)
+    if (!sessionOptions(await ctx.session.get({ sessionID: event.sessionID })).delivery) return
+    // Prevent bypass through built-in shell/edit, plugin and child-session tools,
+    // and Code Mode while the participating-tool policy is locked. Runtime hooks
+    // still repeat the check at invocation time; hiding a model tool is not the
+    // authorization boundary by itself.
+    const locked = !data.state || planningStatus(data.state, fingerprint(cwd, ["."])).locked
+     if (locked && event.tools && typeof event.tools === "object") {
+      for (const name of Object.keys(event.tools)) if (requiresImplementationTool(name)) delete event.tools[name]
+    }
+    if (!data.state || ["verified", "blocked"].includes(data.state.status)) {
+      const checkpoint = discoveryCheckpoint(data.discovery)
+      if (checkpoint) event.system.push({ type: "text", text: checkpoint })
+      return
+    }
+    const dir = runDirectory(cwd, event.sessionID, data.state.runId)
+    const recovery = deliveryRecovery(data.state, { report: join(dir, "report.json"), planningStatus: planningStatus(data.state, fingerprint(cwd, ["."])) })
+    const checkpoint = recoveryMessages([], recovery).map((message: { content: string }) => message.content).join("\n")
+    event.system.push({ type: "text", text: `${data.guidance || DELIVERY_INVARIANTS}\n\nCurrent delivery recovery record (not authorization; recompute freshness before checks/finish):\n${checkpoint}\n\n${deliveryPhaseGuidance(data.state)}` })
+  }))
+
+  registrations.push(await ctx.session.hook("prompt", async event => serialized(event.sessionID, async () => {
+    const { cwd, data, options: opts } = await scope(event.sessionID)
+    if (!opts.delivery) return
+    const workflow = data.state && !["verified", "blocked"].includes(data.state.status) ? data.state.workflowMode : opts.workflow
+    const routed = routeGuidance(event.prompt.text, { cwd, profiles })
+    let guidance = DELIVERY_INVARIANTS + "\n" + deliveryPhaseGuidance(data.state) + "\n" + policyDescription(workflow)
+    if (workflow === "standard") guidance += "\nA valid required plan allows implementation; final evidence and review stay mandatory."
+    if (/\b(test|typescript|route|backend|api)\b/i.test(event.prompt.text)) guidance += `\n${TEST_INFRASTRUCTURE_GUIDANCE}`
+    if (data.discovery.active && workflow === "strict") guidance += `\n${PLANNING_START}`
+    const routedText = formatGuidance(routed); if (routedText) guidance += `\n${routedText}`
+    if (data.extraGuidance) guidance += `\nTask-specific delivery context:\n${data.extraGuidance}`
+    if (data.required.length) guidance += `\nUser-owned required validators are enforced: ${JSON.stringify(data.required)}. Run every required check; do not bypass.`
+    if (looksInformational(event.prompt.text)) guidance += `\nReceipt check: informational/read-only ask; answer directly or use verification none/advisory. Do not enter a repair loop.`
+    data.lastPrompt = event.prompt.text
+    data.guidance = `${guidance}\n\n${data.state ? deliveryRecovery(data.state, { report: join(runDirectory(cwd, event.sessionID, data.state.runId), "report.json") }) ? "Existing delivery state remains authoritative; do not trust summary claims over current report/fingerprint." : "" : ""}`
+    const internal = event.metadata?.carthagentRecovery === true || event.metadata?.carthagentBudget === true
+    if (!internal) { data.discovery = newDiscovery(!looksInformational(event.prompt.text)); data.nudges = 0; data.touched = false }
+    await ctx.storage.set(sessionKey(event.sessionID), data)
+  })))
+
+  registrations.push(await ctx.command.transform(editor => {
+    editor.add({ name: "delivery-budget-status", description: "Show this session's persistent delivery budget", execute: async ({ sessionID }) => {
+      const { data } = await scope(sessionID)
+      await ctx.session.prompt({ sessionID, delivery: "steer", metadata: { carthagentBudget: true }, text: `Delivery budget status: ${JSON.stringify(budgetSnapshot(data.budget))}` })
+    } })
+    editor.add({ name: "delivery-budget-reset", description: "Explicitly authorize a fresh budget for this session", execute: async ({ sessionID }) => {
+      const snapshot = await serialized(sessionID, async () => {
+        const { data, options: opts } = await scope(sessionID); clearTimeout(budgetTimers.get(sessionID)); budgetTimers.delete(sessionID); data.budget = newBudget(budgetLimits((name: string) => opts[limitOptions[name]] ?? opts[name] ?? "0")); await ctx.storage.set(sessionKey(sessionID), data)
+        for (const key of admittedCalls) if (key.startsWith(`${sessionID}\0`)) admittedCalls.delete(key)
+        return budgetSnapshot(data.budget)
+      })
+      await ctx.session.prompt({ sessionID, delivery: "steer", metadata: { carthagentBudget: true }, text: `Delivery budget explicitly reset: ${JSON.stringify(snapshot)}` })
+    } })
+  }))
+
+  const abort = new AbortController()
+  void (async () => {
+    try {
+      for await (const event of ctx.event.subscribe({ signal: abort.signal })) {
+        if (event.type === "session.idle" && event.data?.sessionID) {
+          const sessionID = event.data.sessionID
+          let followup: string | undefined
+          await serialized(sessionID, async () => {
+            const { cwd, data, session } = await scope(sessionID)
+            const reason = budgetReason(data.budget)
+            if (reason && !data.budget.stopped) {
+              data.budget.stopped = reason
+              await ctx.storage.set(sessionKey(sessionID), data)
+               await ctx.session.interrupt({ sessionID, resume: false })
+              return
+            }
+            if (data.discovery.active) data.discovery = discoveryEvent(data.discovery, "blocked")
+            const state = data.state
+            if (!state || data.nudges >= 2 || ["verified", "blocked"].includes(state.status) || !data.touched || verificationMode(state.plan) !== "required" || session.outcome !== "succeeded") {
+              await ctx.storage.set(sessionKey(sessionID), data)
+              return
+            }
+            const release = lockWorkspace(cwd)
+            try {
+              const dir = runDirectory(cwd, sessionID, state.runId)
+              assertActiveReport(cwd, join(dir, "report.json"))
+              data.state = reconcileReport(join(dir, "report.json"), state)
+              const hash = fingerprint(cwd, ["."])
+              const issues = completionIssues(data.state, cwd, hash)
+              const fresh = data.state.handoff?.fingerprint === hash
+              if (fresh || !Object.values(issues).some(items => items.length)) {
+                await ctx.storage.set(sessionKey(sessionID), data)
+                return
+              }
+              const repairReason = budgetReason(data.budget, "repair")
+              if (repairReason) {
+                data.budget.stopped = repairReason
+                await ctx.storage.set(sessionKey(sessionID), data)
+                await ctx.session.interrupt({ sessionID, resume: false })
+                return
+              }
+              data.budget.repairs++
+              data.nudges++
+              const pending = issues.pendingChecks.join(", ") || "none"
+              await ctx.storage.set(sessionKey(sessionID), data)
+              followup = `Delivery follow-up ${data.nudges}/2: the required contract has no fresh verified handoff. Pending checks: ${pending}. Inspect current delivery_status, repair the actual cause, rerun checks and finish verified, or record status=blocked with specific limitations. Do not repeat a success claim or weaken obligations.`
+            } catch (error) {
+              console.error("Carthagent delivery recovery failed closed", error)
+            } finally { release() }
+          })
+          if (followup) await ctx.session.prompt({ sessionID, metadata: { carthagentRecovery: true }, text: followup, delivery: "steer" })
+          for (const key of admittedCalls) if (key.startsWith(`${sessionID}\0`)) admittedCalls.delete(key)
+        }
+      }
+    } catch (error) { if (!abort.signal.aborted) console.error("Carthagent delivery event subscription failed", error) }
+  })()
+  return async () => {
+    if (disposed) return
+    disposed = true; abort.abort()
+    admittedCalls.clear()
+    for (const timer of budgetTimers.values()) clearTimeout(timer)
+    budgetTimers.clear()
+    await Promise.all(registrations.map(registration => registration.dispose()))
+    serial.clear()
+  }
+}
+
+function requiresImplementationTool(name: string) {
+  // V2 exposes namespaced tools as `namespace_name` in model context and hooks.
+  const toolName = name.startsWith("carthagent_") ? name.slice("carthagent_".length) : name
+  return !["read", "ls", "find", "grep", "execute", "code_nav", "delivery_probe", "delivery_plan", "delivery_revise", "delivery_design", "delivery_status", "delivery_finish", "delivery-budget-status", "delivery-budget-reset"].includes(toolName)
+}

package/plugins/carthagent/src/server/device-auth.ts

@@ -0,0 +1,91 @@
+import type { Credential } from '@opencode/schema/credential';
+import { Integration as IntegrationSchema } from '@opencode/schema/integration';
+import { randomUUID } from 'node:crypto';
+import { CloudClient, cloudControlUrl, oauthCredentials } from '../../../../lib/cloud/client.mjs';
+import { shipInstallId } from '../../../../lib/ship-telemetry.mjs';
+
+const METHOD_ID = 'carthagent-device';
+const MAX_EXPIRY_MS = 15 * 60_000;
+
+type Flow = {
+  controller: AbortController;
+  authorization: Awaited<ReturnType<CloudClient['createDeviceAuthorization']>>;
+  callback: Promise<Credential.OAuth>;
+  expiresAt: number;
+  timer: ReturnType<typeof setTimeout>;
+};
+
+export function createDeviceAuthController({ env = process.env, fetchImpl = globalThis.fetch, agentDir, now = Date.now, sleep = (ms: number, signal?: AbortSignal) => new Promise<void>((resolve, reject) => {
+  if (signal?.aborted) return reject(signal.reason);
+  const timer = setTimeout(resolve, ms);
+  signal?.addEventListener('abort', () => { clearTimeout(timer); reject(signal.reason); }, { once: true });
+}) }: {
+  env?: NodeJS.ProcessEnv; fetchImpl?: typeof fetch; agentDir: string; now?: () => number;
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}) {
+  const client = new CloudClient({ baseUrl: cloudControlUrl(env), fetchImpl, sleep: ms => sleep(ms) });
+  const flows = new Map<string, Flow>();
+  const remove = (id: string) => {
+    const flow = flows.get(id);
+    if (!flow) return false;
+    clearTimeout(flow.timer);
+    flows.delete(id);
+    return true;
+  };
+  const start = async (signal?: AbortSignal) => {
+    // Bound active generations; expired callbacks are aborted by their timer.
+    for (const [id, flow] of flows) if (flow.expiresAt <= now()) { flow.controller.abort(new Error('expired_token')); remove(id); }
+    if (flows.size >= 4) throw new Error('too_many_auth_flows');
+    const request = client.request as unknown as (path: string, options: { method: string; body: unknown; signal?: AbortSignal }) => Promise<{
+      userCode: string; verificationUri: string; verificationUriComplete?: string; expiresIn: number; interval: number; deviceCode: string;
+    }>;
+    const createAuthorization = (input: { clientName: string; installId: string }, signal?: AbortSignal) => request.call(client, '/v1/device/authorizations', {
+      method: 'POST', body: input, signal,
+    });
+    const authorization = await createAuthorization({
+      clientName: `Carthagent OpenCode (${process.env.HOSTNAME || 'device'})`,
+      installId: shipInstallId({ agentDir }),
+    }, signal);
+    const flowId = randomUUID();
+    const controller = new AbortController();
+    const expiresAt = now() + Math.min(MAX_EXPIRY_MS, Math.max(1, Number(authorization.expiresIn) || 600) * 1000);
+    const timer = setTimeout(() => controller.abort(new Error('expired_token')), Math.max(1, expiresAt - now()));
+    const flow: Flow = { controller, authorization, callback: Promise.resolve({} as Credential.OAuth), expiresAt, timer };
+    flows.set(flowId, flow);
+    const callback = (async () => {
+      try {
+        const interval = Math.max(1000, Number(authorization.interval || 5) * 1000);
+        while (now() < expiresAt) {
+          controller.signal.throwIfAborted();
+          try {
+            const tokens = await client.pollDeviceToken({ deviceCode: authorization.deviceCode, signal: controller.signal });
+            return { type: 'oauth', methodID: IntegrationSchema.MethodID.make(METHOD_ID), ...oauthCredentials(tokens, now()) } as Credential.OAuth;
+          } catch (error) {
+            if (!(error instanceof Error) || !('code' in error) || error.code !== 'authorization_pending') throw error;
+          }
+          await sleep(interval, controller.signal);
+        }
+        throw new Error('expired_token');
+      } finally { remove(flowId); }
+    })();
+    // Avoid unhandled rejection for RPC-only starts; native authorize still
+    // awaits this same promise and receives the original rejection.
+    void callback.catch(() => {});
+    flow.callback = callback;
+    return { flowId, authorization, callback, expiresAt };
+  };
+  return {
+    start,
+    cancel(flowId: string) {
+      const flow = flows.get(flowId);
+      if (!flow) return false;
+      flow.controller.abort(new Error('cancelled'));
+      return remove(flowId);
+    },
+    async cleanup() {
+      for (const flow of flows.values()) { clearTimeout(flow.timer); flow.controller.abort(new Error('plugin_unloaded')); }
+      flows.clear();
+      await Promise.resolve();
+    },
+  };
+}