pi-dcg 0.0.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows the spirit of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and uses semantic versioning for releases.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-17
+
+### Added
+
+- Initial `pi-dcg` Pi package.
+- Guarding for agent `bash` calls and user `!`/`!!` commands through dcg's hook protocol.
+- Pi-native handling for allow, deny, and ask decisions.
+- Bounded, cancellable dcg subprocess execution with configurable bridge error behavior.
+- Startup health status and `/dcg` diagnostics command.
+- Best-effort install/update telemetry following monorepo policy.
+- Unit and integration coverage for protocol, process, client, and extension behavior.
+
+### Fixed
+
+- Made checked-command sealing idempotent when the package is loaded at more than one Pi scope.
+- Avoided empty stdin writes for probe commands, which could race with fast-exiting dcg binaries and falsely report that dcg was unavailable.
+
+### Security
+
+- Sealed approved agent `bash` commands and their input references so later Pi handlers cannot replace them after the dcg check.
+- Kept dcg allow-once commands out of model-visible denial results while retaining user-only UI guidance.
+- Documented that Pi's RPC control-channel `bash` command does not emit an extension event and therefore cannot be guarded by `pi-dcg`.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,40 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing these standards and may remove, edit, or reject contributions that are not aligned with this Code of Conduct.
+
+## Scope
+
+This Code of Conduct applies within all project spaces and when an individual is officially representing the project in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the maintainers through GitHub. All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing
+
+Thanks for your interest in contributing to `pi-dcg`.
+
+## Development setup
+
+```bash
+npm install
+npm run -w packages/pi-dcg check
+npm run -w packages/pi-dcg test
+```
+
+This package is source-distributed: Pi loads its TypeScript extension files directly. There is no runtime build step.
+
+## Local testing
+
+Install the checkout into a temporary Pi project:
+
+```bash
+mkdir -p <test-project>
+cd <test-project>
+pi install -l /path/to/pi-mono/packages/pi-dcg
+pi
+```
+
+Run `/dcg` to verify binary discovery. Exercise safe and destructive fixtures only through `dcg test` or a disposable sandbox; do not run genuinely destructive commands to test the bridge.
+
+## Pull request checklist
+
+- Run `npm run -w packages/pi-dcg check`.
+- Run `npm run -w packages/pi-dcg test`.
+- Run `npm audit --omit=dev`.
+- Run `npm run -w packages/pi-dcg pack:dry-run` and inspect included files.
+- Update README and SECURITY for behavior, environment, process, or data-flow changes.
+- Update CHANGELOG for notable changes.
+- Keep examples free of credentials, command secrets, machine-specific paths, and local policy content.
+
+## Coding guidelines
+
+- Keep extension wiring in `extensions/index.ts` and reusable behavior in `src/`.
+- Start dcg directly; never interpolate command text into a shell command.
+- Preserve hard-deny, cancellation, output-bound, cwd, and child-environment invariants documented in AGENTS.md.
+- Treat environment variable names and defaults as public API.
+- Keep tests independent of a real dcg installation.
+
+## Code of conduct
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose Mocito
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# pi-dcg
+
+Guard Pi shell commands with [Destructive Command Guard (dcg)](https://github.com/Dicklesworthstone/destructive_command_guard) before they execute.
+
+`pi-dcg` is a Pi extension bridge. It does not bundle dcg, replace dcg policy, or provide a sandbox.
+
+## Requirements
+
+- Node.js 20.6 or newer
+- Pi 0.80 or newer
+- A separately installed `dcg` executable; dcg 0.6.8 or newer is recommended
+
+Install dcg using its [upstream installation instructions](https://github.com/Dicklesworthstone/destructive_command_guard#installation), review its release-verification guidance, and confirm that the binary is visible in the same environment as Pi:
+
+```bash
+dcg --version
+```
+
+> **Separate license:** dcg is external software with its own nonstandard license, including an OpenAI/Anthropic rider. It is not included in this package. Review the [dcg license](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/LICENSE) before installing or using it.
+
+## Install
+
+```bash
+pi install npm:pi-dcg
+```
+
+For project-local installation:
+
+```bash
+pi install -l npm:pi-dcg
+```
+
+For a one-off checkout test:
+
+```bash
+pi -e /path/to/pi-mono/packages/pi-dcg
+```
+
+## What it guards
+
+By default, the extension checks both Pi shell events available to extensions:
+
+- agent calls to Pi's built-in `bash` tool;
+- user `!command` and `!!command` invocations.
+
+Pi's separate RPC control-channel `{"type":"bash"}` command does not emit either event in current Pi releases and cannot be intercepted by `pi-dcg`; see [Limitations](#limitations).
+
+For every non-empty command, the extension starts dcg directly without a shell, sends a Claude-compatible `PreToolUse` payload on stdin, and waits for dcg's decision before Pi executes the command.
+
+Pi allows `tool_call` handlers to rewrite tool arguments in sequence. `pi-dcg` checks mutations made by earlier handlers, then seals both the approved `command` value and its input reference. If a later handler attempts to replace either one, Pi blocks the tool call rather than executing a command dcg did not check.
+
+| dcg response | Pi behavior |
+| --- | --- |
+| Empty stdout / explicit `allow` | Execute the command |
+| `permissionDecision: "deny"` | Block and show bounded rule/remediation details |
+| `permissionDecision: "ask"` | Ask for confirmation when UI is available; otherwise block |
+| Bridge failure | Allow by default, visibly marking dcg unavailable; configurable to block |
+
+Hard denials are never converted into one-click approvals. When dcg provides an allow-once code, `pi-dcg` shows the exact `dcg allow-once ...` command only in a user-facing UI notification. It is deliberately excluded from the model-visible blocked tool result so an agent cannot redeem the exception itself.
+
+Run `/dcg` to probe the binary and show the active bridge configuration.
+
+## Why this uses hook mode
+
+The short upstream Pi recipe calls `dcg --robot test`. `pi-dcg` deliberately uses dcg's normal hook protocol instead because the current hook path provides the behavior expected from an agent integration:
+
+- Pi-specific agent profiles and their pack/allowlist changes;
+- hook policy and confidence handling;
+- scoped allow-once checks and pending exception records;
+- history/audit integration;
+- structured rule, severity, explanation, and remediation fields.
+
+The bridge sets `PI_CODING_AGENT=true` so dcg resolves `[agents.pi]` policy. It also sets `DCG_NO_SELF_HEAL=1` only for the child process: dcg's default hook self-healing targets Claude settings and should not rewrite those files merely because Pi asked for a decision.
+
+## Configuration
+
+`pi-dcg` uses environment variables for bridge behavior. dcg's own `DCG_*` variables and TOML files continue to control policy.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `PI_DCG_BIN` | `DCG_BIN`, then `dcg` | Executable name or path. Leading `~/` is expanded. |
+| `PI_DCG_TIMEOUT_MS` | `5000` | Whole child-process timeout, from 100 to 60000 ms. |
+| `PI_DCG_ON_ERROR` | `allow` | `allow` (fail open) or `block` when the bridge cannot obtain a valid decision. |
+| `PI_DCG_GUARD_USER_BASH` | `1` | Set to `0`, `false`, `no`, or `off` to skip user `!`/`!!` commands. |
+
+Examples:
+
+```bash
+PI_DCG_BIN="$HOME/.local/bin/dcg" pi
+PI_DCG_ON_ERROR=block pi
+PI_DCG_GUARD_USER_BASH=0 pi
+```
+
+`PI_DCG_ON_ERROR=block` covers bridge failures such as a missing executable, timeout, malformed output, or oversized output. It cannot turn dcg's own intentional fail-open analysis decisions into failures. Configure dcg itself for stricter heredoc and hook behavior.
+
+### Pi-specific dcg policy
+
+Current dcg releases recognize the `pi` agent profile:
+
+```toml
+# ~/.config/dcg/config.toml or .dcg.toml
+[agents.pi]
+trust_level = "medium"
+extra_packs = ["database", "containers"]
+```
+
+Use real pack or category IDs reported by `dcg packs`.
+
+## Process and data handling
+
+- The command is sent only to the local dcg child process over stdin.
+- The extension never invokes a shell to start dcg.
+- dcg runs with Pi's current working directory, preserving project policy and allow-once scope.
+- Captured stdout and stderr share a 512 KiB limit.
+- dcg's human stderr output is captured rather than copied into Pi logs or model context.
+- Denial text sent back to Pi is bounded to prevent context flooding.
+
+On startup, this package also sends the monorepo-standard best-effort install/update telemetry ping to `mocito.dev`, once per package version. It is disabled in CI and respects Pi offline and telemetry settings. It contains the package name/version and platform/runtime/architecture only—never commands, paths, dcg output, or policy.
+
+## Limitations
+
+This extension intercepts Pi events, not operating-system process execution. It cannot see:
+
+- custom tools that execute commands under another tool name;
+- Pi's RPC control-channel `{"type":"bash"}` command, which does not emit a `user_bash` event;
+- `pi.exec()` or child processes started internally by another extension;
+- destructive behavior performed directly through non-shell tools;
+- the contents of an opaque script invoked only as `./script.sh` unless dcg can infer or inspect the payload;
+- commands that dcg itself intentionally allows after a parse, size, or deadline fallback.
+
+`user_bash` handlers are first-result-wins in Pi. An earlier extension that fully handles `!` commands can prevent later handlers, including `pi-dcg`, from seeing them.
+
+Use a container, VM, sandbox, restricted credentials, backups, and review controls when a hard security boundary is required.
+
+## Development
+
+```bash
+npm install
+npm run -w packages/pi-dcg check
+npm run -w packages/pi-dcg test
+npm run -w packages/pi-dcg pack:dry-run
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) and [SECURITY.md](./SECURITY.md).
+
+## License
+
+`pi-dcg` is MIT licensed. dcg is separate external software and is not covered by this package's MIT license. See [THIRD-PARTY-NOTICES](./THIRD-PARTY-NOTICES).

package/SECURITY.md

@@ -0,0 +1,57 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest released version of `pi-dcg`.
+
+## Reporting a vulnerability
+
+Do not open a public issue for a suspected vulnerability. Report privately through the repository maintainer's GitHub security contact. Include a description, reproduction steps, affected versions, and suggested mitigation when available.
+
+## Security model
+
+`pi-dcg` is a local guardrail bridge, not a sandbox or authorization boundary. Pi extensions execute with the same permissions as the user running Pi, and dcg is a separately installed executable with those permissions.
+
+The bridge:
+
+- intercepts Pi's built-in agent `bash` calls and, by default, user `!`/`!!` commands;
+- starts the configured dcg executable directly without a shell;
+- sends command text to that local child process on stdin;
+- sets the child cwd to Pi's current working directory;
+- validates dcg's structured stdout decision;
+- seals an approved agent `bash` command and its input reference so later `tool_call` handlers cannot replace them unchecked;
+- keeps allow-once commands out of model-visible denial results and shows them only through user-facing UI notifications;
+- captures but does not log or forward dcg stderr;
+- bounds child output and denial text;
+- blocks a command when its check is cancelled;
+- preserves hard dcg denials without a one-click bypass.
+
+The child receives Pi's environment because dcg policy is intentionally configured through `DCG_*` variables. `pi-dcg` additionally sets `PI_CODING_AGENT=true`, `DCG_NO_SELF_HEAL=1`, and no-color flags for that child. Environment values are never logged or sent over the network by this package.
+
+### Failure behavior
+
+Bridge failures default to visible fail-open behavior to match dcg's integration philosophy. Set `PI_DCG_ON_ERROR=block` to block when the bridge cannot start dcg, times out, exceeds output limits, receives a nonzero exit, or cannot validate stdout.
+
+This setting cannot detect dcg's internal intentional fail-open paths, which may return a valid allow after size, parse, AST, or deadline fallback. Configure dcg itself for stricter analysis where supported.
+
+### Known bypasses
+
+The extension cannot intercept arbitrary process creation. Important bypasses include:
+
+- custom tools with other names;
+- Pi's RPC control-channel `{"type":"bash"}` command, which does not emit a `user_bash` event;
+- `pi.exec()` and child processes started inside another extension;
+- non-shell file, database, cloud, or API operations;
+- opaque generated scripts and dynamic payloads dcg cannot inspect;
+- earlier Pi `user_bash` handlers that fully replace execution;
+- dcg rules, packs, safe patterns, allowlists, bypass variables, and fail-open analysis behavior.
+
+Use least-privilege credentials, version control, backups, containers/VMs, and OS-level sandboxing when destructive operations must be prevented rather than merely guarded.
+
+## External dcg dependency and license
+
+`pi-dcg` does not bundle or redistribute Destructive Command Guard. Users install it separately and are responsible for reviewing its code, releases, provenance, and nonstandard license, including its OpenAI/Anthropic rider. This package's MIT license does not apply to dcg.
+
+## Telemetry
+
+On startup, the package sends a best-effort install/update telemetry ping to `mocito.dev` once per package version unless disabled by CI, `PI_OFFLINE`, `PI_TELEMETRY`, or Pi's `enableInstallTelemetry` setting. The ping includes only package name/version and platform/runtime/architecture. It never includes commands, paths, dcg decisions, stderr, configuration, environment variables, prompts, credentials, or policy.

package/THIRD-PARTY-NOTICES

@@ -0,0 +1,9 @@
+THIRD-PARTY NOTICES
+
+pi-dcg interoperates with Destructive Command Guard (dcg), maintained by Jeffrey Emanuel and contributors:
+https://github.com/Dicklesworthstone/destructive_command_guard
+
+Destructive Command Guard is NOT included, copied, linked, or redistributed in the pi-dcg npm package. It is a separately installed executable governed by its own nonstandard license, including an OpenAI/Anthropic rider:
+https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/LICENSE
+
+The MIT license distributed with pi-dcg applies only to pi-dcg's independently authored bridge code and documentation. Users are responsible for reviewing and complying with dcg's separate license before installing or using dcg.

package/extensions/index.ts

@@ -0,0 +1,282 @@
+import {
+  isToolCallEventType,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { loadDcgBridgeConfig, type DcgBridgeConfig } from "../src/config.js";
+import {
+  DcgClient,
+  DcgProcessError,
+  isRecommendedDcgVersion,
+  MINIMUM_RECOMMENDED_DCG_VERSION,
+  type DcgClientLike,
+} from "../src/dcg-client.js";
+import { reportInstallTelemetry } from "../src/install-telemetry.js";
+import { formatDcgDecision, getDcgAllowOnceCommand } from "../src/protocol.js";
+
+const STATUS_KEY = "pi-dcg";
+const MAX_COMMAND_PREVIEW_CHARS = 4_000;
+const CHECKED_BASH_SEAL = Symbol.for("pi-dcg.checked-bash-seal");
+
+type GuardOutcome = { block: false } | { block: true; reason: string };
+type Health = "active" | "degraded" | "unknown";
+
+export interface PiDcgDependencies {
+  client?: DcgClientLike;
+  config?: DcgBridgeConfig;
+}
+
+function truncate(value: string, maxChars: number): string {
+  if (value.length <= maxChars) return value;
+  return `${value.slice(0, Math.max(0, maxChars - 1))}…`;
+}
+
+function errorMessage(error: unknown): string {
+  if (error instanceof DcgProcessError) return error.message;
+  if (error instanceof Error && error.message.trim()) return error.message;
+  return "dcg failed for an unknown reason";
+}
+
+function sealCheckedBashCommand(
+  event: { input: { command: string } },
+  command: string,
+): void {
+  const input = event.input;
+  const seal = (event as unknown as Record<PropertyKey, unknown>)[CHECKED_BASH_SEAL];
+  if (seal !== undefined) {
+    if (
+      typeof seal === "object"
+      && seal !== null
+      && "input" in seal
+      && "command" in seal
+      && seal.input === input
+      && seal.command === command
+    ) {
+      return;
+    }
+    throw new Error("pi-dcg found an inconsistent existing bash command seal");
+  }
+
+  Object.defineProperty(input, "command", {
+    configurable: false,
+    enumerable: true,
+    get: () => command,
+    set: () => {
+      throw new Error("pi-dcg blocked a bash command mutation after its safety check");
+    },
+  });
+  Object.defineProperty(event, "input", {
+    configurable: false,
+    enumerable: true,
+    get: () => input,
+    set: () => {
+      throw new Error("pi-dcg blocked a bash arguments replacement after its safety check");
+    },
+  });
+  Object.defineProperty(event, CHECKED_BASH_SEAL, {
+    configurable: false,
+    enumerable: false,
+    value: { input, command },
+    writable: false,
+  });
+}
+
+function notify(
+  ctx: ExtensionContext,
+  message: string,
+  type: "info" | "warning" | "error",
+): void {
+  if (!ctx.hasUI) return;
+  try {
+    ctx.ui.notify(message, type);
+  } catch {
+    // UI failures must never alter a dcg decision.
+  }
+}
+
+function setStatus(
+  ctx: ExtensionContext,
+  health: Health,
+  config: DcgBridgeConfig,
+  version?: string,
+): void {
+  if (!ctx.hasUI) return;
+  try {
+    if (health === "active") {
+      const label = version ? `dcg ${version}` : "dcg active";
+      ctx.ui.setStatus(STATUS_KEY, ctx.ui.theme.fg("success", `shield ${label}`));
+      return;
+    }
+    if (health === "degraded") {
+      const behavior = config.onError === "block" ? "blocking" : "fail-open";
+      ctx.ui.setStatus(STATUS_KEY, ctx.ui.theme.fg("warning", `shield dcg unavailable (${behavior})`));
+      return;
+    }
+    ctx.ui.setStatus(STATUS_KEY, ctx.ui.theme.fg("muted", "shield dcg checking"));
+  } catch {
+    // Status rendering is advisory and must never alter a dcg decision.
+  }
+}
+
+function clearStatus(ctx: ExtensionContext): void {
+  if (!ctx.hasUI) return;
+  try {
+    ctx.ui.setStatus(STATUS_KEY, undefined);
+  } catch {
+    // The session is already shutting down.
+  }
+}
+
+export default function piDcg(
+  pi: ExtensionAPI,
+  dependencies: PiDcgDependencies = {},
+): void {
+  reportInstallTelemetry();
+
+  const config = dependencies.config ?? loadDcgBridgeConfig();
+  const client = dependencies.client ?? new DcgClient(config);
+  let version: string | undefined;
+  let lastNotifiedError: string | undefined;
+  let warnedAboutVersion = false;
+
+  const markHealthy = (ctx: ExtensionContext, detectedVersion = version): void => {
+    version = detectedVersion;
+    lastNotifiedError = undefined;
+    setStatus(ctx, "active", config, version);
+  };
+
+  const markDegraded = (ctx: ExtensionContext, error: unknown): void => {
+    const message = errorMessage(error);
+    setStatus(ctx, "degraded", config, version);
+    if (ctx.hasUI && message !== lastNotifiedError) {
+      lastNotifiedError = message;
+      const behavior = config.onError === "block" ? "Commands will be blocked." : "Commands will be allowed (fail-open).";
+      notify(ctx, `pi-dcg: ${message} ${behavior}`, "warning");
+    }
+  };
+
+  const guard = async (
+    command: string,
+    cwd: string,
+    ctx: ExtensionContext,
+  ): Promise<GuardOutcome> => {
+    if (!command.trim()) return { block: false };
+
+    let result;
+    try {
+      result = await client.check(command, cwd, ctx.signal);
+      markHealthy(ctx);
+    } catch (error) {
+      if (error instanceof DcgProcessError && error.code === "aborted") {
+        return { block: true, reason: "dcg check was cancelled; the command was not run." };
+      }
+      markDegraded(ctx, error);
+      if (config.onError === "block") {
+        return {
+          block: true,
+          reason: `dcg could not evaluate this command: ${errorMessage(error)} Blocking because PI_DCG_ON_ERROR=block.`,
+        };
+      }
+      return { block: false };
+    }
+
+    if (result.decision === "allow") return { block: false };
+    const reason = formatDcgDecision(result);
+    if (result.decision === "deny") {
+      const allowOnce = getDcgAllowOnceCommand(result);
+      if (allowOnce) {
+        notify(ctx, `dcg blocked the command. To authorize this exact command manually: ${allowOnce}`, "warning");
+      }
+      return { block: true, reason };
+    }
+
+    if (!ctx.hasUI) {
+      return { block: true, reason: `${reason}\n\nNo interactive UI is available to confirm this warning.` };
+    }
+
+    let approved = false;
+    try {
+      approved = await ctx.ui.confirm(
+        "dcg requires confirmation",
+        `Command:\n${truncate(command, MAX_COMMAND_PREVIEW_CHARS)}\n\n${reason}`,
+      );
+    } catch {
+      return { block: true, reason: `${reason}\n\nThe confirmation dialog failed, so the command was blocked.` };
+    }
+    return approved ? { block: false } : { block: true, reason: `${reason}\n\nThe command was not approved.` };
+  };
+
+  pi.on("session_start", async (_event, ctx) => {
+    if (!ctx.hasUI) return;
+    setStatus(ctx, "unknown", config);
+    try {
+      const probe = await client.probe(ctx.cwd);
+      markHealthy(ctx, probe.version);
+      if (!isRecommendedDcgVersion(probe.version) && !warnedAboutVersion) {
+        warnedAboutVersion = true;
+        notify(
+          ctx,
+          `pi-dcg: found dcg ${probe.version}; dcg ${MINIMUM_RECOMMENDED_DCG_VERSION} or newer is recommended.`,
+          "warning",
+        );
+      }
+    } catch (error) {
+      markDegraded(ctx, error);
+    }
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    if (!isToolCallEventType("bash", event)) return undefined;
+    const command = event.input.command;
+    const outcome = await guard(command, ctx.cwd, ctx);
+    if (outcome.block) return { block: true, reason: outcome.reason };
+
+    // Pi executes this same input object after all tool_call handlers finish.
+    // Seal the checked value so a later extension cannot replace it unchecked.
+    sealCheckedBashCommand(event, command);
+    return undefined;
+  });
+
+  if (config.guardUserBash) {
+    pi.on("user_bash", async (event, ctx) => {
+      const outcome = await guard(event.command, event.cwd, ctx);
+      if (!outcome.block) return undefined;
+      return {
+        result: {
+          output: outcome.reason,
+          exitCode: 1,
+          cancelled: false,
+          truncated: false,
+        },
+      };
+    });
+  }
+
+  pi.registerCommand("dcg", {
+    description: "Show pi-dcg status and configuration",
+    handler: async (args, ctx) => {
+      if (args.trim()) {
+        notify(ctx, "Usage: /dcg", "warning");
+        return;
+      }
+      try {
+        const probe = await client.probe(ctx.cwd);
+        markHealthy(ctx, probe.version);
+        const coverage = config.guardUserBash
+          ? "agent bash and user !/!! commands (RPC bash excluded)"
+          : "agent bash commands";
+        notify(
+          ctx,
+          `pi-dcg is active\nBinary: ${config.binary}\nVersion: ${probe.version}\nCoverage: ${coverage}\nBridge errors: ${config.onError}`,
+          "info",
+        );
+      } catch (error) {
+        markDegraded(ctx, error);
+      }
+    },
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    clearStatus(ctx);
+  });
+}

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./extensions/index.js";

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "pi-dcg",
+  "version": "0.0.0",
+  "description": "Guard Pi shell commands with Destructive Command Guard.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Jose Mocito",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jvm/pi-mono.git",
+    "directory": "packages/pi-dcg"
+  },
+  "bugs": {
+    "url": "https://github.com/jvm/pi-mono/issues"
+  },
+  "homepage": "https://github.com/jvm/pi-mono/tree/main/packages/pi-dcg#readme",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "dcg",
+    "destructive-command-guard",
+    "command-safety",
+    "guardrails"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "extensions",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
+    "THIRD-PARTY-NOTICES"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.mjs",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.0",
+    "@types/node": "^26.1.0",
+    "tsx": "^4.23.0",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,57 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const DEFAULT_DCG_TIMEOUT_MS = 5_000;
+export const MIN_DCG_TIMEOUT_MS = 100;
+export const MAX_DCG_TIMEOUT_MS = 60_000;
+export const MAX_DCG_OUTPUT_BYTES = 512 * 1024;
+
+export type DcgErrorMode = "allow" | "block";
+
+export interface DcgBridgeConfig {
+  binary: string;
+  timeoutMs: number;
+  maxOutputBytes: number;
+  onError: DcgErrorMode;
+  guardUserBash: boolean;
+}
+
+function isFalseEnvValue(value: string): boolean {
+  return ["0", "false", "no", "off", "n"].includes(value.trim().toLowerCase());
+}
+
+function parseTimeout(value: string | undefined): number {
+  if (value === undefined || value.trim() === "") return DEFAULT_DCG_TIMEOUT_MS;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < MIN_DCG_TIMEOUT_MS || parsed > MAX_DCG_TIMEOUT_MS) {
+    return DEFAULT_DCG_TIMEOUT_MS;
+  }
+  return parsed;
+}
+
+function expandHome(path: string, home: string): string {
+  if (path === "~") return home;
+  if (path.startsWith("~/") || path.startsWith("~\\")) {
+    return join(home, path.slice(2));
+  }
+  return path;
+}
+
+export function loadDcgBridgeConfig(
+  env: NodeJS.ProcessEnv = process.env,
+  home: string = homedir(),
+): DcgBridgeConfig {
+  const configuredBinary = env.PI_DCG_BIN?.trim() || env.DCG_BIN?.trim() || "dcg";
+  const onError = env.PI_DCG_ON_ERROR?.trim().toLowerCase() === "block" ? "block" : "allow";
+  const guardUserBash = env.PI_DCG_GUARD_USER_BASH === undefined
+    ? true
+    : !isFalseEnvValue(env.PI_DCG_GUARD_USER_BASH);
+
+  return {
+    binary: expandHome(configuredBinary, home),
+    timeoutMs: parseTimeout(env.PI_DCG_TIMEOUT_MS),
+    maxOutputBytes: MAX_DCG_OUTPUT_BYTES,
+    onError,
+    guardUserBash,
+  };
+}

package/src/dcg-client.ts

@@ -0,0 +1,208 @@
+import { spawn } from "node:child_process";
+import type { DcgBridgeConfig } from "./config.js";
+import { parseDcgHookResponse, type DcgDecision } from "./protocol.js";
+
+export const MINIMUM_RECOMMENDED_DCG_VERSION = "0.6.8";
+
+export type DcgProcessErrorCode =
+  | "aborted"
+  | "output_limit"
+  | "spawn_failed"
+  | "timed_out";
+
+export class DcgProcessError extends Error {
+  constructor(
+    message: string,
+    public readonly code: DcgProcessErrorCode,
+  ) {
+    super(message);
+    this.name = "DcgProcessError";
+  }
+}
+
+export interface ProcessRequest {
+  command: string;
+  args: string[];
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  input?: string;
+  timeoutMs: number;
+  maxOutputBytes: number;
+  signal?: AbortSignal;
+}
+
+export interface ProcessResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+}
+
+export type ProcessExecutor = (request: ProcessRequest) => Promise<ProcessResult>;
+
+export const executeProcess: ProcessExecutor = (request) => new Promise((resolve, reject) => {
+  if (request.signal?.aborted) {
+    reject(new DcgProcessError("dcg check was cancelled", "aborted"));
+    return;
+  }
+
+  const child = spawn(request.command, request.args, {
+    cwd: request.cwd,
+    env: request.env,
+    stdio: [request.input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+    windowsHide: true,
+  });
+
+  let settled = false;
+  let stdout = "";
+  let stderr = "";
+  let outputBytes = 0;
+
+  const cleanup = (): void => {
+    clearTimeout(timeout);
+    request.signal?.removeEventListener("abort", onAbort);
+  };
+
+  const rejectOnce = (error: Error, kill = false): void => {
+    if (settled) return;
+    settled = true;
+    cleanup();
+    if (kill && child.exitCode === null) child.kill();
+    reject(error);
+  };
+
+  const append = (stream: "stdout" | "stderr", chunk: Buffer): void => {
+    if (settled) return;
+    outputBytes += chunk.byteLength;
+    if (outputBytes > request.maxOutputBytes) {
+      rejectOnce(new DcgProcessError("dcg output exceeded the bridge limit", "output_limit"), true);
+      return;
+    }
+    if (stream === "stdout") stdout += chunk.toString("utf8");
+    else stderr += chunk.toString("utf8");
+  };
+
+  const onAbort = (): void => {
+    rejectOnce(new DcgProcessError("dcg check was cancelled", "aborted"), true);
+  };
+
+  const timeout = setTimeout(() => {
+    rejectOnce(new DcgProcessError(`dcg did not finish within ${request.timeoutMs}ms`, "timed_out"), true);
+  }, request.timeoutMs);
+
+  request.signal?.addEventListener("abort", onAbort, { once: true });
+  child.stdout?.on("data", (chunk: Buffer) => append("stdout", chunk));
+  child.stderr?.on("data", (chunk: Buffer) => append("stderr", chunk));
+  child.once("error", (error) => {
+    rejectOnce(new DcgProcessError(`could not start dcg: ${error.message}`, "spawn_failed"));
+  });
+  child.once("close", (exitCode) => {
+    if (settled) return;
+    settled = true;
+    cleanup();
+    resolve({ stdout, stderr, exitCode });
+  });
+
+  if (request.input !== undefined) {
+    if (!child.stdin) {
+      rejectOnce(new DcgProcessError("could not open dcg stdin", "spawn_failed"), true);
+      return;
+    }
+    child.stdin.once("error", (error) => {
+      rejectOnce(new DcgProcessError(`could not send the command to dcg: ${error.message}`, "spawn_failed"), true);
+    });
+    child.stdin.end(request.input, "utf8");
+  }
+});
+
+export interface DcgProbeResult {
+  version: string;
+}
+
+export interface DcgClientLike {
+  check(command: string, cwd: string, signal?: AbortSignal): Promise<DcgDecision>;
+  probe(cwd: string, signal?: AbortSignal): Promise<DcgProbeResult>;
+}
+
+function processEnvironment(environment: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  return {
+    ...environment,
+    PI_CODING_AGENT: "true",
+    DCG_NO_SELF_HEAL: "1",
+    DCG_NO_COLOR: "1",
+    NO_COLOR: "1",
+  };
+}
+
+function parseVersion(stdout: string): string {
+  const match = stdout.match(/(?:^|\s)v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/);
+  if (match?.[1]) return match[1];
+  const firstLine = stdout.split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+  if (!firstLine) throw new Error("dcg --version returned no version");
+  return firstLine.replace(/^dcg\s+/i, "");
+}
+
+function parseSemver(value: string): [number, number, number] | undefined {
+  const match = value.match(/^v?(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return undefined;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+export function isRecommendedDcgVersion(version: string): boolean {
+  const actual = parseSemver(version);
+  const minimum = parseSemver(MINIMUM_RECOMMENDED_DCG_VERSION);
+  if (!actual || !minimum) return false;
+  for (let index = 0; index < actual.length; index += 1) {
+    if (actual[index] !== minimum[index]) return actual[index] > minimum[index];
+  }
+  return true;
+}
+
+export class DcgClient implements DcgClientLike {
+  constructor(
+    public readonly config: DcgBridgeConfig,
+    private readonly processExecutor: ProcessExecutor = executeProcess,
+    private readonly environment: NodeJS.ProcessEnv = process.env,
+  ) {}
+
+  async check(command: string, cwd: string, signal?: AbortSignal): Promise<DcgDecision> {
+    const input = `${JSON.stringify({
+      hook_event_name: "PreToolUse",
+      tool_name: "Bash",
+      tool_input: { command },
+      cwd,
+    })}\n`;
+    const result = await this.processExecutor({
+      command: this.config.binary,
+      args: [],
+      cwd,
+      env: processEnvironment(this.environment),
+      input,
+      timeoutMs: this.config.timeoutMs,
+      maxOutputBytes: this.config.maxOutputBytes,
+      signal,
+    });
+
+    if (result.exitCode !== 0) {
+      const exit = result.exitCode === null ? "a signal" : `exit code ${result.exitCode}`;
+      throw new Error(`dcg hook failed with ${exit}`);
+    }
+    return parseDcgHookResponse(result.stdout);
+  }
+
+  async probe(cwd: string, signal?: AbortSignal): Promise<DcgProbeResult> {
+    const result = await this.processExecutor({
+      command: this.config.binary,
+      args: ["--version"],
+      cwd,
+      env: processEnvironment(this.environment),
+      timeoutMs: Math.min(this.config.timeoutMs, 1_500),
+      maxOutputBytes: this.config.maxOutputBytes,
+      signal,
+    });
+    if (result.exitCode !== 0) {
+      const exit = result.exitCode === null ? "a signal" : `exit code ${result.exitCode}`;
+      throw new Error(`dcg --version failed with ${exit}`);
+    }
+    return { version: parseVersion(result.stdout) };
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export const PACKAGE_NAME = "pi-dcg";
+
+export * from "./config.js";
+export * from "./dcg-client.js";
+export * from "./protocol.js";

package/src/install-telemetry.ts

@@ -0,0 +1,104 @@
+import { readFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+const PACKAGE_NAME = "pi-dcg";
+const INSTALL_TELEMETRY_URL = "https://mocito.dev/api/report-install";
+const INSTALL_TELEMETRY_TIMEOUT_MS = 5000;
+const CI_ENVIRONMENT_VARIABLES = [
+  "APPVEYOR",
+  "BITBUCKET_BUILD_NUMBER",
+  "BUILDKITE",
+  "CIRCLECI",
+  "CODESPACES",
+  "DRONE",
+  "GITHUB_ACTIONS",
+  "GITLAB_CI",
+  "JENKINS_URL",
+  "NETLIFY",
+  "TEAMCITY_VERSION",
+  "TF_BUILD",
+  "TRAVIS",
+  "VERCEL",
+];
+
+interface InstallTelemetryState {
+  lastReportedVersion?: string;
+}
+
+interface PiSettingsDocument {
+  enableInstallTelemetry?: unknown;
+}
+
+function readJsonFile(path: string): unknown {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as unknown;
+  } catch {
+    return {};
+  }
+}
+
+function isTruthyEnvFlag(value: string | undefined): boolean {
+  if (!value) return false;
+  return value === "1" || value.toLowerCase() === "true" || value.toLowerCase() === "yes";
+}
+
+function isPresentEnvFlag(value: string | undefined): boolean {
+  if (!value) return false;
+  const normalized = value.toLowerCase();
+  return normalized !== "0" && normalized !== "false" && normalized !== "no";
+}
+
+function isCiEnvironment(): boolean {
+  if (isTruthyEnvFlag(process.env.CI)) return true;
+  return CI_ENVIRONMENT_VARIABLES.some((name) => isPresentEnvFlag(process.env[name]));
+}
+
+function isInstallTelemetryEnabled(): boolean {
+  if (isCiEnvironment()) return false;
+  if (isTruthyEnvFlag(process.env.PI_OFFLINE)) return false;
+  if (process.env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(process.env.PI_TELEMETRY);
+
+  const settings = readJsonFile(join(getAgentDir(), "settings.json")) as PiSettingsDocument;
+  return settings.enableInstallTelemetry !== false;
+}
+
+function getPackageVersion(): string {
+  const packageJson = readJsonFile(fileURLToPath(new URL("../package.json", import.meta.url))) as { version?: unknown };
+  return typeof packageJson.version === "string" && packageJson.version.length > 0 ? packageJson.version : "0.0.0";
+}
+
+function getInstallTelemetryUserAgent(version: string): string {
+  const runtimeVersions = process.versions as NodeJS.ProcessVersions & { bun?: string };
+  const runtime = runtimeVersions.bun ? `bun/${runtimeVersions.bun}` : `node/${process.version}`;
+  return `${PACKAGE_NAME}/${version} (${process.platform}; ${runtime}; ${process.arch})`;
+}
+
+async function reportInstallTelemetryAsync(): Promise<void> {
+  try {
+    if (!isInstallTelemetryEnabled()) return;
+
+    const version = getPackageVersion();
+    const extensionsDir = join(getAgentDir(), "extensions");
+    const statePath = join(extensionsDir, "pi-dcg-install.json");
+    const state = readJsonFile(statePath) as InstallTelemetryState;
+    if (state.lastReportedVersion === version) return;
+
+    await mkdir(extensionsDir, { recursive: true });
+    await writeFile(statePath, `${JSON.stringify({ lastReportedVersion: version }, null, 2)}\n`, "utf8");
+
+    const params = new URLSearchParams({ tool: PACKAGE_NAME, version });
+    await fetch(`${INSTALL_TELEMETRY_URL}?${params.toString()}`, {
+      headers: { "User-Agent": getInstallTelemetryUserAgent(version) },
+      signal: AbortSignal.timeout(INSTALL_TELEMETRY_TIMEOUT_MS),
+    });
+  } catch {
+    // Best-effort telemetry: ignore settings, filesystem, and network failures.
+  }
+}
+
+export function reportInstallTelemetry(): void {
+  void reportInstallTelemetryAsync();
+}

package/src/protocol.ts

@@ -0,0 +1,134 @@
+const MAX_REASON_CHARS = 12_000;
+const MAX_FIELD_CHARS = 8_000;
+
+interface DcgRemediation {
+  safeAlternative?: string;
+  explanation?: string;
+  allowOnceCommand?: string;
+}
+
+interface DcgHookOutput {
+  permissionDecision: "allow" | "deny" | "ask";
+  permissionDecisionReason?: string;
+  allowOnceCode?: string;
+  allowOnceFullHash?: string;
+  ruleId?: string;
+  packId?: string;
+  severity?: string;
+  confidence?: number;
+  remediation?: DcgRemediation;
+}
+
+export type DcgDecision =
+  | { decision: "allow" }
+  | { decision: "deny" | "ask"; hook: DcgHookOutput };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+
+function optionalNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function parseRemediation(value: unknown): DcgRemediation | undefined {
+  if (!isRecord(value)) return undefined;
+  const remediation = {
+    safeAlternative: optionalString(value.safeAlternative),
+    explanation: optionalString(value.explanation),
+    allowOnceCommand: optionalString(value.allowOnceCommand),
+  };
+  return Object.values(remediation).some((field) => field !== undefined) ? remediation : undefined;
+}
+
+export function parseDcgHookResponse(stdout: string): DcgDecision {
+  const trimmed = stdout.trim().replace(/^\uFEFF/, "");
+  if (trimmed === "") return { decision: "allow" };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed) as unknown;
+  } catch {
+    throw new Error("dcg returned malformed JSON");
+  }
+
+  if (!isRecord(parsed) || !isRecord(parsed.hookSpecificOutput)) {
+    throw new Error("dcg returned an unsupported hook response");
+  }
+
+  const raw = parsed.hookSpecificOutput;
+  const permissionDecision = raw.permissionDecision;
+  if (permissionDecision !== "allow" && permissionDecision !== "deny" && permissionDecision !== "ask") {
+    throw new Error("dcg hook response has an unknown permission decision");
+  }
+  if (permissionDecision === "allow") return { decision: "allow" };
+
+  return {
+    decision: permissionDecision,
+    hook: {
+      permissionDecision,
+      permissionDecisionReason: optionalString(raw.permissionDecisionReason),
+      allowOnceCode: optionalString(raw.allowOnceCode),
+      allowOnceFullHash: optionalString(raw.allowOnceFullHash),
+      ruleId: optionalString(raw.ruleId),
+      packId: optionalString(raw.packId),
+      severity: optionalString(raw.severity),
+      confidence: optionalNumber(raw.confidence),
+      remediation: parseRemediation(raw.remediation),
+    },
+  };
+}
+
+function truncate(value: string, maxChars: number): string {
+  if (value.length <= maxChars) return value;
+  return `${value.slice(0, Math.max(0, maxChars - 1))}…`;
+}
+
+function redactAllowOnceCommands(value: string): string {
+  return value.replace(/\bdcg\s+allow-once\b[^\r\n]*/gi, "[manual authorization command hidden]");
+}
+
+function extractReason(message: string | undefined): string | undefined {
+  if (!message) return undefined;
+  const match = message.match(/(?:^|\n)Reason:\s*([^\n]*(?:\n(?!\s*(?:Explanation|Rule|Pack|Command):)[^\n]*)*)/i);
+  const reason = match?.[1]?.trim();
+  return reason || truncate(message.trim(), MAX_FIELD_CHARS);
+}
+
+function metadata(hook: DcgHookOutput): string | undefined {
+  const fields = [hook.severity, hook.ruleId ?? hook.packId].filter(Boolean);
+  if (hook.confidence !== undefined) fields.push(`confidence ${hook.confidence.toFixed(2)}`);
+  return fields.length > 0 ? fields.join(" · ") : undefined;
+}
+
+export function getDcgAllowOnceCommand(
+  result: Exclude<DcgDecision, { decision: "allow" }>,
+): string | undefined {
+  const command = result.hook.remediation?.allowOnceCommand
+    ?? (result.hook.allowOnceCode ? `dcg allow-once ${result.hook.allowOnceCode}` : undefined);
+  return command ? truncate(command.trim(), MAX_FIELD_CHARS) : undefined;
+}
+
+export function formatDcgDecision(result: Exclude<DcgDecision, { decision: "allow" }>): string {
+  const { hook } = result;
+  const lines = [result.decision === "deny" ? "Blocked by dcg." : "dcg requires confirmation."];
+  const meta = metadata(hook);
+  if (meta) lines.push(meta);
+
+  const reason = extractReason(hook.permissionDecisionReason);
+  if (reason) lines.push(`Reason: ${truncate(reason, MAX_FIELD_CHARS)}`);
+
+  const explanation = hook.remediation?.explanation?.trim();
+  if (explanation && explanation !== reason) {
+    lines.push(`Details: ${truncate(explanation, MAX_FIELD_CHARS)}`);
+  }
+
+  const alternative = hook.remediation?.safeAlternative?.trim();
+  if (alternative) lines.push(`Safer alternative: ${truncate(alternative, MAX_FIELD_CHARS)}`);
+
+  return truncate(redactAllowOnceCommands(lines.join("\n\n")), MAX_REASON_CHARS);
+}