@tech-leads-club/harness-toolkit 0.10.5 → 0.11.0

package/src/entrypoints/subagent-stop.ts

@@ -14,9 +14,10 @@ export const subagentStopHandler: Handler = async (
   // rule asks for. It cannot change the decision below ([/decisions/ad-100.md](/decisions/ad-100.md)).
   await observeForRules(event, ctx);
 
-  const handoff = coreFacade.handoff.readHandoff(event.projectDir, event.provider);
-  // why: `blockers` is per-project, and every Task subagent shares the parent's session_id
-  // (anthropics/claude-code#7881), so this cannot tell its own subagent apart from another. A "budget"
+  const handoff = coreFacade.handoff.readHandoff(event.projectDir, event.provider, event.sessionKey);
+  // why: `blockers` is per-session ([/decisions/ad-122.md](/decisions/ad-122.md)), and every Task subagent
+  // shares the parent's session_id (anthropics/claude-code#7881), so this cannot tell its own subagent apart
+  // from another. A "budget"
   // category means the session's turn budget ran out, not that the tree is broken — unlike a gate
   // failure, it is not valid evidence here ([/decisions/ad-073.md](/decisions/ad-073.md)).
   const isBudgetBlocker = handoff.last_failure_category === "budget";

package/src/entrypoints/support.ts

@@ -98,10 +98,11 @@ export type TurnScope = {
 export async function computeTurnScope(
   root: string,
   provider: string,
+  sessionKey: string,
   policy: Pick<Policy, "codePaths">,
 ): Promise<TurnScope> {
-  const seal = coreFacade.handoff.handoffInjectable(root);
-  const handoff = seal.ok ? coreFacade.handoff.readHandoff(root, provider) : undefined;
+  const seal = coreFacade.handoff.handoffInjectable(root, sessionKey);
+  const handoff = seal.ok ? coreFacade.handoff.readHandoff(root, provider, sessionKey) : undefined;
   const turnBase = handoff?.turn_base_sha ?? "HEAD";
   const changedFiles = await listChangedRepoFiles(root, turnBase);
   const codeTargets = filterCodeTargets(changedFiles, policy.codePaths);
@@ -128,12 +129,13 @@ export async function computeTurnScope(
 export async function pendingCommentViolations(
   root: string,
   provider: string,
+  sessionKey: string,
   policy: Pick<Policy, "comments" | "codePaths">,
 ): Promise<CommentFinding[]> {
   if (!policy.comments.enabled || policy.comments.onViolation !== "followup") {
     return [];
   }
-  const scope = await computeTurnScope(root, provider, policy);
+  const scope = await computeTurnScope(root, provider, sessionKey, policy);
   if (scope.commentTargets.length === 0) {
     return [];
   }

package/src/entrypoints/tool-after.ts

@@ -68,7 +68,7 @@ async function commentEditAdvisory(event: HarnessEvent, ctx: HandlerContext): Pr
   if (targets.length === 0) {
     return null;
   }
-  const handoff = coreFacade.handoff.readHandoff(event.projectDir, event.provider);
+  const handoff = coreFacade.handoff.readHandoff(event.projectDir, event.provider, event.sessionKey);
   const hits = await coreFacade.commentPolicy.scanAddedComments(
     event.projectDir,
     targets,
@@ -133,6 +133,26 @@ export const toolAfterHandler: Handler = async (event: HarnessEvent, ctx: Handle
     });
   }
 
+  if (ctx.policy.secrets.redactOutput && event.toolOutput) {
+    const output = event.toolOutput;
+    const matches = coreFacade.secretScan.scanForSecrets(output);
+    if (matches.length > 0) {
+      let masked = output;
+      // why: reversed so each replacement's [start, end) offsets, computed against the original string, stay
+      // valid as the string's length changes underneath earlier ones.
+      for (const match of [...matches].reverse()) {
+        const placeholder = coreFacade.secretScan.placeholderFor(
+          event.projectDir,
+          event.sessionKey,
+          output.slice(match.start, match.end),
+          match.kind,
+        );
+        masked = `${masked.slice(0, match.start)}${placeholder}${masked.slice(match.end)}`;
+      }
+      return { kind: "rewriteOutput", output: masked };
+    }
+  }
+
   const untrustedDecision = coreFacade.untrusted.evaluateUntrustedContent({
     root: event.projectDir,
     sessionKey: event.sessionKey,

package/src/entrypoints/tool-before.ts

@@ -26,7 +26,7 @@ async function commentGateBeforeCommit(event: HarnessEvent, ctx: HandlerContext)
   if (!coreFacade.rules.triggerMatches({ kind: "commit" }, context)) {
     return { kind: "abstain" };
   }
-  const hits = await pendingCommentViolations(event.projectDir, event.provider, ctx.policy);
+  const hits = await pendingCommentViolations(event.projectDir, event.provider, event.sessionKey, ctx.policy);
   if (hits.length === 0) {
     return { kind: "abstain" };
   }
@@ -183,6 +183,7 @@ export const toolBeforeHandler: Handler = async (
     filePath: filePathOf(event),
     command: event.command,
     isReadEvent: event.event === "read.before",
+    protectedPaths: ctx.protectedPaths,
   });
   if (floor.kind !== "allow") {
     // invariant: one rail owns the record of every shell decision. The floor short-circuits before the shell

package/src/platform/paths.ts

@@ -128,6 +128,10 @@ export function bootDir(root: string): string {
   return join(projectStateDir(root), "boot");
 }
 
+export function handoffSessionsDir(root: string): string {
+  return join(projectStateDir(root), "handoff-sessions");
+}
+
 // why: inside the state directory on purpose — the baseline that proves the policy was not switched off
 // inherits the same protection as the policy itself.
 export function policyBaselineDir(root: string): string {

package/src/platform/process.ts

@@ -1,7 +1,43 @@
 import { spawn } from "node:child_process";
+import { hostname } from "node:os";
 
 const TIMEOUT_EXIT_CODE = 124;
 
+/** Asks the OS whether a pid exists. Injected so the ESRCH and EPERM branches are testable on every platform. */
+export type ProcessProbe = (pid: number) => void;
+
+const defaultProbe: ProcessProbe = (pid) => {
+  process.kill(pid, 0);
+};
+
+/**
+ * Whether the process that recorded `pid`/`host` is still running, right now, on this machine.
+ *
+ * why: a pid means nothing on another host, so a mismatch answers "alive" rather than guessing.
+ * `process.kill(pid, 0)` sends no signal, it only asks whether the process exists; `ESRCH` is the one answer
+ * that proves it does not. Extracted from `gate.lock.ts`'s original `isLockOwnerGone`, its only consumer — a
+ * pid outlives one long-running gate command's own duration ([/decisions/ad-122.md](/decisions/ad-122.md)).
+ */
+export function isProcessAlive(
+  pid: number,
+  host: string,
+  thisHost: string = hostname(),
+  probe: ProcessProbe = defaultProbe,
+): boolean {
+  if (host !== thisHost) {
+    return true;
+  }
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return true;
+  }
+  try {
+    probe(pid);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code !== "ESRCH";
+  }
+}
+
 export async function readStdinText(): Promise<string> {
   const chunks: Buffer[] = [];
   for await (const chunk of process.stdin) {

package/src/providers/claude/claude.capabilities.ts

@@ -8,7 +8,9 @@ export function claudeCapabilities(): ProviderCapabilities {
     nativeLoopCounter: false,
     dedicatedShellEvent: false,
     toolInputRewrite: true,
-    toolOutputRewrite: true,
+    // why: `updatedToolOutput` is documented on every event this adapter fires PostToolUse/PostToolUseFailure
+    // for — both of the after-events a rewrite could ever apply to.
+    toolOutputRewriteOn: ["tool.after", "tool.failure"],
     contextAtToolBefore: true,
     contextAtToolAfter: true,
     // why: `Stop` accepts `hookSpecificOutput.additionalContext` for feedback that continues the turn, which is

package/src/providers/claude/claude.inbound.ts

@@ -2,7 +2,7 @@ import { isEffortLevel } from "../../contracts/effort.ts";
 import type { EffortLevel, HarnessEvent, HarnessEventKind } from "../../contracts/index.ts";
 import { sanitizeSegment } from "../../platform/sanitize.ts";
 
-const EVENT_KIND_BY_HOOK: Record<string, HarnessEventKind> = {
+export const EVENT_KIND_BY_HOOK: Record<string, HarnessEventKind> = {
   SessionStart: "session.start",
   SessionEnd: "session.end",
   UserPromptSubmit: "prompt.submit",
@@ -16,6 +16,40 @@ const EVENT_KIND_BY_HOOK: Record<string, HarnessEventKind> = {
 
 const MCP_TOOL_NAME = /^mcp__/;
 
+type ToolNameFanOutRule = { match: RegExp | string; kind: HarnessEventKind };
+
+// why: PreToolUse fans out by tool_name — Claude has no dedicated shell/MCP/read event.
+export const PRE_TOOL_USE_FAN_OUT: readonly ToolNameFanOutRule[] = [
+  { match: "Bash", kind: "shell.before" },
+  { match: MCP_TOOL_NAME, kind: "mcp.before" },
+  { match: "Read", kind: "read.before" },
+];
+
+// why: PostToolUse fans out the same way, for the after-half of each of those tool classes.
+export const POST_TOOL_USE_FAN_OUT: readonly ToolNameFanOutRule[] = [
+  { match: "Bash", kind: "shell.after" },
+  { match: MCP_TOOL_NAME, kind: "mcp.after" },
+  { match: "Edit", kind: "edit.after" },
+  { match: "Write", kind: "edit.after" },
+];
+
+function matchFanOut(
+  table: readonly ToolNameFanOutRule[],
+  toolName: string | undefined,
+  fallback: HarnessEventKind,
+): HarnessEventKind {
+  if (toolName === undefined) {
+    return fallback;
+  }
+  for (const rule of table) {
+    const matched = typeof rule.match === "string" ? rule.match === toolName : rule.match.test(toolName);
+    if (matched) {
+      return rule.kind;
+    }
+  }
+  return fallback;
+}
+
 function asString(value: unknown): string | undefined {
   return typeof value === "string" ? value : undefined;
 }
@@ -57,31 +91,12 @@ function effortFor(raw: Record<string, unknown>): EffortLevel | undefined {
   return isEffortLevel(level) ? level : undefined;
 }
 
-// why: PreToolUse fans out by tool_name — Claude has no dedicated shell/MCP/read event.
 function preToolUseKind(toolName: string | undefined): HarnessEventKind {
-  if (toolName === "Bash") {
-    return "shell.before";
-  }
-  if (toolName && MCP_TOOL_NAME.test(toolName)) {
-    return "mcp.before";
-  }
-  if (toolName === "Read") {
-    return "read.before";
-  }
-  return "tool.before";
+  return matchFanOut(PRE_TOOL_USE_FAN_OUT, toolName, "tool.before");
 }
 
 function postToolUseKind(toolName: string | undefined): HarnessEventKind {
-  if (toolName === "Bash") {
-    return "shell.after";
-  }
-  if (toolName && MCP_TOOL_NAME.test(toolName)) {
-    return "mcp.after";
-  }
-  if (toolName === "Edit" || toolName === "Write") {
-    return "edit.after";
-  }
-  return "tool.after";
+  return matchFanOut(POST_TOOL_USE_FAN_OUT, toolName, "tool.after");
 }
 
 /** Never throws on a malformed payload — returns null instead. */

package/src/providers/claude/claude.outbound.ts

@@ -57,6 +57,10 @@ export function claudeRender(decision: Decision, event: HarnessEvent): Rendered
         stdout: JSON.stringify({ hookSpecificOutput: { hookEventName, updatedInput: decision.input } }),
         exitCode: 0,
       };
+    // why: the documented schema for updatedToolOutput places it at the top of the JSON, unlike every other
+    // field this adapter emits — nesting it under hookSpecificOutput would not be read.
+    case "rewriteOutput":
+      return { stdout: JSON.stringify({ updatedToolOutput: decision.output }), exitCode: 0 };
     default: {
       const exhaustive: never = decision;
       throw new Error(`unreachable decision kind: ${JSON.stringify(exhaustive)}`);

package/src/providers/claude/claude.wiring.ts

@@ -31,6 +31,10 @@ export function claudeSettingsPath(): string {
   return join(claudeConfigDir(), "settings.json");
 }
 
+export function claudeWiringTargets(): string[] {
+  return [claudeSettingsPath()];
+}
+
 // why: exec form only, on every platform — it bypasses shell tokenization, so there is no quoting variant to get wrong.
 export function claudeWiring(runtime: RuntimePaths): ProviderWiring {
   const entries: WiringEntry[] = ENTRY_SPECS.map((spec) => ({

package/src/providers/claude/index.ts

@@ -4,7 +4,7 @@ import { detectClaude } from "./claude.detect.ts";
 import { claudeToEvent } from "./claude.inbound.ts";
 import { claudeRender } from "./claude.outbound.ts";
 import { claudePolicyDefaults } from "./claude.policy-defaults.ts";
-import { claudeWiring } from "./claude.wiring.ts";
+import { claudeWiring, claudeWiringTargets } from "./claude.wiring.ts";
 
 export const claudeProvider: ProviderPort = {
   name: "claude",
@@ -14,4 +14,5 @@ export const claudeProvider: ProviderPort = {
   toEvent: claudeToEvent,
   render: claudeRender,
   wiring: claudeWiring,
+  wiringTargets: claudeWiringTargets,
 };

package/src/providers/cursor/cursor.capabilities.ts

@@ -8,7 +8,9 @@ export function cursorCapabilities(): ProviderCapabilities {
     nativeLoopCounter: true,
     dedicatedShellEvent: true,
     toolInputRewrite: true,
-    toolOutputRewrite: true,
+    // why: `updated_mcp_tool_output` is scoped to `afterMCPExecution` only — `afterShellExecution` and
+    // `afterFileEdit` are documented as observation-only, with no equivalent field.
+    toolOutputRewriteOn: ["mcp.after"],
     contextAtToolBefore: false,
     contextAtToolAfter: true,
     // why: the `stop` output schema carries `followup_message` and nothing else, so a context decision raised there

package/src/providers/cursor/cursor.inbound.ts

@@ -1,7 +1,7 @@
 import type { HarnessEvent, HarnessEventKind } from "../../contracts/index.ts";
 import { sanitizeSegment } from "../../platform/sanitize.ts";
 
-const EVENT_KIND_BY_HOOK: Record<string, HarnessEventKind> = {
+export const EVENT_KIND_BY_HOOK: Record<string, HarnessEventKind> = {
   sessionStart: "session.start",
   sessionEnd: "session.end",
   beforeSubmitPrompt: "prompt.submit",

package/src/providers/cursor/cursor.outbound.ts

@@ -35,6 +35,15 @@ export function cursorRender(decision: Decision, _event: HarnessEvent): Rendered
       return { stdout: JSON.stringify({ followup_message: decision.text }), exitCode: 0 };
     case "rewriteInput":
       return { stdout: JSON.stringify({ updated_input: decision.input }), exitCode: 0 };
+    // hazard: Cursor's docs declare `updated_mcp_tool_output` as an object with no documented inner keys —
+    // `result_json` mirrors the field this same event reads the original output from (`cursor.inbound.ts`).
+    // `provider.degrade.ts` only lets `rewriteOutput` reach here for `mcp.after`; every other event is already
+    // `context` by the time render runs.
+    case "rewriteOutput":
+      return {
+        stdout: JSON.stringify({ updated_mcp_tool_output: { result_json: decision.output } }),
+        exitCode: 0,
+      };
     default: {
       const exhaustive: never = decision;
       throw new Error(`unreachable decision kind: ${JSON.stringify(exhaustive)}`);

package/src/providers/cursor/cursor.wiring.ts

@@ -12,6 +12,14 @@ type EntrySpec = {
 };
 
 // why: mirrors bin/write-user-hooks.mjs verbatim — same hook keys, timeouts, failClosed/matcher/loopLimit values, and handler order.
+export function cursorHooksPath(): string {
+  return join(cursorConfigDir(), "hooks.json");
+}
+
+export function cursorWiringTargets(): string[] {
+  return [cursorHooksPath()];
+}
+
 const ENTRY_SPECS: readonly EntrySpec[] = [
   { hookEvent: "sessionStart", handler: "session-start", timeoutSeconds: 10 },
   { hookEvent: "sessionEnd", handler: "session-end", timeoutSeconds: 10 },
@@ -57,7 +65,7 @@ export function cursorWiring(runtime: RuntimePaths): ProviderWiring {
   }));
 
   return {
-    target: join(cursorConfigDir(), "hooks.json"),
+    target: cursorHooksPath(),
     strategy: "replace",
     entries,
   };

package/src/providers/cursor/index.ts

@@ -4,7 +4,7 @@ import { detectCursor } from "./cursor.detect.ts";
 import { cursorToEvent } from "./cursor.inbound.ts";
 import { cursorRender } from "./cursor.outbound.ts";
 import { cursorPolicyDefaults } from "./cursor.policy-defaults.ts";
-import { cursorWiring } from "./cursor.wiring.ts";
+import { cursorWiring, cursorWiringTargets } from "./cursor.wiring.ts";
 
 export const cursorProvider: ProviderPort = {
   name: "cursor",
@@ -14,4 +14,5 @@ export const cursorProvider: ProviderPort = {
   toEvent: cursorToEvent,
   render: cursorRender,
   wiring: cursorWiring,
+  wiringTargets: cursorWiringTargets,
 };

package/src/providers/provider.degrade.ts

@@ -20,6 +20,10 @@ const NO_HUMAN_PREFIX = "No operator is answering prompts in this permission mod
 const NO_HUMAN_MODES = new Set(["bypassPermissions", "dontAsk"]);
 const ADVISORY_PREFIX = "ADVISORY — this provider cannot enforce: ";
 const TRUNCATION_MARKER = "\n…(truncated — over context budget)";
+// why: the model already saw the masked output verbatim on a host where rewrite is unsupported for this event —
+// a `context` notice cannot erase that, so it names the constraint instead of pretending the value is gone.
+const REWRITE_OUTPUT_UNAVAILABLE_NOTICE =
+  "A secret-shaped value was masked in this tool's output and must not be repeated.";
 
 function isEnforcing(decision: Decision): boolean {
   return (
@@ -133,6 +137,21 @@ export function degrade(
     };
   }
 
+  if (decision.kind === "rewriteOutput") {
+    if (capabilities.toolOutputRewriteOn.includes(event.event)) {
+      return decision;
+    }
+    // why: a degraded rewriteOutput becomes exactly a context decision, and recursing here — instead of
+    // duplicating the handling below — is what runs it through the same canCarryContext/budget logic every
+    // other context decision already gets, with no special case for this one.
+    return degrade(
+      { kind: "context", text: REWRITE_OUTPUT_UNAVAILABLE_NOTICE },
+      event,
+      capabilities,
+      options,
+    );
+  }
+
   if (decision.kind === "context") {
     // hazard: contextAtToolBefore and contextAtToolAfter were declared by every adapter and read by
     // nothing. A provider that cannot carry context on the current event would have had the text rendered

package/src/providers/provider.port.ts

@@ -17,4 +17,5 @@ export type ProviderPort = {
   toEvent(raw: Record<string, unknown>): HarnessEvent | null;
   render(decision: Decision, event: HarnessEvent): Rendered;
   wiring(runtime: RuntimePaths): ProviderWiring;
+  wiringTargets(): string[];
 };

package/tools/new-provider.ts

@@ -0,0 +1,251 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// hazard: this file lived at tools/dev/new-provider.ts (two levels below root) until it moved to tools/ —
+// tools/dev/ is excluded from the published package, and bin/tlc-cli.ts's `new-provider` subcommand imports
+// this module at runtime, so a real install had no file to import at all.
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+// invariant: mirrors provider.contract.test.ts's own safety check ("provider name is safe as a state-file
+// key segment") — no whitespace, no slashes. Reserved names collide with this scaffold's own file layout
+// (`index.ts`) or the generic module concept ("provider").
+const UNSAFE_NAME = /[\s/\\]/;
+const RESERVED_NAMES = new Set(["index", "provider"]);
+
+export type NameValidity = { ok: true } | { ok: false; reason: string };
+
+export function validateProviderName(name: string): NameValidity {
+  if (name.length === 0) {
+    return { ok: false, reason: "provider name must not be empty" };
+  }
+  if (UNSAFE_NAME.test(name)) {
+    return { ok: false, reason: "provider name must not contain whitespace or a slash" };
+  }
+  if (RESERVED_NAMES.has(name.toLowerCase())) {
+    return { ok: false, reason: `"${name}" is a reserved name` };
+  }
+  return { ok: true };
+}
+
+function capitalize(name: string): string {
+  return name.length === 0 ? name : `${name[0]?.toUpperCase()}${name.slice(1)}`;
+}
+
+function detectStub(name: string): string {
+  const cap = capitalize(name);
+  return `// why: always false until real detection logic replaces it, so the provider stays inert.
+export function detect${cap}(_raw: unknown): boolean {
+  return false;
+}
+`;
+}
+
+function capabilitiesStub(name: string): string {
+  return `import type { HarnessEventKind, ProviderCapabilities } from "../../contracts/index.ts";
+
+export function ${name}Capabilities(): ProviderCapabilities {
+  return {
+    enforcesHooks: true,
+    askSupportedOn: [],
+    sessionEnv: false,
+    nativeLoopCounter: false,
+    dedicatedShellEvent: false,
+    toolInputRewrite: false,
+    // why: a placeholder, deliberately not a real HarnessEventKind — fails assertSatisfiesContract until replaced.
+    toolOutputRewriteOn: ["TODO-fill-in-real-capabilities" as unknown as HarnessEventKind],
+    contextAtToolBefore: false,
+    contextAtToolAfter: false,
+    contextAtStop: false,
+    sessionStartContextReliable: false,
+    toolOutputAtAfter: false,
+    usageInPayload: false,
+    effortSignal: false,
+    thoughtEvent: false,
+  };
+}
+`;
+}
+
+function policyDefaultsStub(name: string): string {
+  return `import type { ProviderPolicyDefaults } from "../../contracts/index.ts";
+
+export function ${name}PolicyDefaults(): ProviderPolicyDefaults {
+  return {
+    blockedPatterns: [],
+    minEffort: null,
+    untrustedTools: [],
+  };
+}
+`;
+}
+
+function inboundStub(name: string): string {
+  return `import type { HarnessEvent, HarnessEventKind } from "../../contracts/index.ts";
+
+// why: empty until this host's own hook names are mapped, so every payload falls through to null.
+export const EVENT_KIND_BY_HOOK: Record<string, HarnessEventKind> = {};
+
+/** Never throws on a malformed payload — returns null instead. */
+export function ${name}ToEvent(_raw: Record<string, unknown>): HarnessEvent | null {
+  return null;
+}
+`;
+}
+
+function wiringStub(name: string): string {
+  return `import type { ProviderWiring, RuntimePaths } from "../../contracts/index.ts";
+
+// why: a placeholder path, until the real file this provider's host reads hooks from is named.
+const WIRING_TARGET = "TODO: replace with the real wiring target path";
+
+export function ${name}WiringTargets(): string[] {
+  return [WIRING_TARGET];
+}
+
+// why: an empty entries list, until this adapter's real hook entries replace it (see claude.wiring.ts's ENTRY_SPECS shape).
+export function ${name}Wiring(_runtime: RuntimePaths): ProviderWiring {
+  return { target: WIRING_TARGET, strategy: "replace", entries: [] };
+}
+`;
+}
+
+function outboundStub(name: string): string {
+  return `import type { Decision, HarnessEvent, Rendered } from "../../contracts/index.ts";
+
+// why: an unconditional abstain, until this host's real hook response schema replaces it.
+export function ${name}Render(_decision: Decision, _event: HarnessEvent): Rendered {
+  return { stdout: null, exitCode: 0 };
+}
+`;
+}
+
+function indexStub(name: string): string {
+  const cap = capitalize(name);
+  return `import type { ProviderPort } from "../provider.port.ts";
+import { ${name}Capabilities } from "./${name}.capabilities.ts";
+import { detect${cap} } from "./${name}.detect.ts";
+import { ${name}ToEvent } from "./${name}.inbound.ts";
+import { ${name}Render } from "./${name}.outbound.ts";
+import { ${name}PolicyDefaults } from "./${name}.policy-defaults.ts";
+import { ${name}Wiring, ${name}WiringTargets } from "./${name}.wiring.ts";
+
+// why: assembled here so \`tlc harness new-provider\` has one ProviderPort to import into provider.registry.ts.
+export const ${name}Provider: ProviderPort = {
+  name: "${name}",
+  detect: detect${cap},
+  capabilities: ${name}Capabilities,
+  policyDefaults: ${name}PolicyDefaults,
+  toEvent: ${name}ToEvent,
+  render: ${name}Render,
+  wiring: ${name}Wiring,
+  wiringTargets: ${name}WiringTargets,
+};
+`;
+}
+
+function docSkeleton(name: string): string {
+  const cap = capitalize(name);
+  const timestamp = new Date().toISOString().slice(0, 10);
+  return `---
+type: Provider
+title: "${cap} provider"
+description: "The ${cap} adapter — capability descriptor, event mapping, and wiring target."
+tags: [provider, ${name}]
+timestamp: "${timestamp}"
+---
+
+# ${cap} provider
+
+Source: \`src/providers/${name}/\`.
+
+## Detection
+
+TODO: describe \`${name}.detect.ts\`'s real detection rule.
+
+## Capability descriptor
+
+\`${name}.capabilities.ts\`:
+
+<!-- generated:capabilities -->
+
+<!-- /generated -->
+
+## Policy defaults
+
+TODO: describe \`${name}.policy-defaults.ts\`'s defaults.
+
+## Event mapping
+
+\`${name}.inbound.ts\` maps ${cap}'s own hook names to \`HarnessEventKind\`:
+
+<!-- generated:event-mapping -->
+
+<!-- /generated -->
+
+## Wiring target
+
+TODO: describe \`${name}.wiring.ts\`'s wiring target and strategy.
+
+## See also
+
+- [/providers/index.md](/providers/index.md)
+`;
+}
+
+export type ScaffoldFile = { path: string; content: string };
+
+export function scaffoldFiles(name: string): ScaffoldFile[] {
+  const dir = join("src", "providers", name);
+  return [
+    { path: join(dir, `${name}.detect.ts`), content: detectStub(name) },
+    { path: join(dir, `${name}.capabilities.ts`), content: capabilitiesStub(name) },
+    { path: join(dir, `${name}.policy-defaults.ts`), content: policyDefaultsStub(name) },
+    { path: join(dir, `${name}.inbound.ts`), content: inboundStub(name) },
+    { path: join(dir, `${name}.wiring.ts`), content: wiringStub(name) },
+    // why: SPEC_DEVIATION — emits 8 files, not the 6 named in design.md/tasks.md, adding `<name>.outbound.ts` and
+    // `index.ts`. Reason: ProviderPort requires a `render` field and an assembled object, the same two-extra-file
+    // shape claude/index.ts and cursor/index.ts already use — without them there is no ProviderPort value for T6
+    // to register or T7 to run through assertSatisfiesContract (see commit 20da58e).
+    { path: join(dir, `${name}.outbound.ts`), content: outboundStub(name) },
+    { path: join(dir, "index.ts"), content: indexStub(name) },
+    { path: join("docs", "providers", `${name}.md`), content: docSkeleton(name) },
+  ];
+}
+
+export function scaffold(name: string, root = repoRoot): NameValidity {
+  const validity = validateProviderName(name);
+  if (!validity.ok) {
+    return validity;
+  }
+  const providerDir = join(root, "src", "providers", name);
+  if (existsSync(providerDir)) {
+    return { ok: false, reason: `${join("src", "providers", name)} already exists` };
+  }
+  for (const file of scaffoldFiles(name)) {
+    const fullPath = join(root, file.path);
+    mkdirSync(dirname(fullPath), { recursive: true });
+    writeFileSync(fullPath, file.content, "utf8");
+  }
+  return { ok: true };
+}
+
+export function main(argv: string[], root = repoRoot): void {
+  const name = argv[0];
+  if (!name) {
+    console.error("usage: node tools/dev/new-provider.ts <name>");
+    process.exitCode = 1;
+    return;
+  }
+  const result = scaffold(name, root);
+  if (!result.ok) {
+    console.error(`new-provider: refusing — ${result.reason}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`new-provider: scaffolded src/providers/${name}/ and docs/providers/${name}.md`);
+}
+
+if (import.meta.main) {
+  main(process.argv.slice(2));
+}