pi-cwd-guard

A small Pi safety extension package for cwd access, protected paths, application configuration guidance, and common destructive bash commands.

What it guards

The extension intercepts these built-in tools:

• read
• write
• edit
• bash

Current working directory guard

Before read, write, or edit runs, the extension strips a leading @ the same way Pi's built-in file tools do, then resolves the tool's path argument against the current working directory.

• If the resolved path is inside the current working directory, the tool continues to the next checks.
• If the resolved path is outside the current working directory and is not covered by allowedOutsideCwdPaths, Pi asks for confirmation.
• If no UI is available, outside-cwd access is blocked by default unless the path is covered by allowedOutsideCwdPaths.

Configuring path exceptions

You can allow specific outside-cwd paths with JSON config files:

• Project-local: .pi/pi-cwd-guard.json
• Global: ~/.pi/agent/extensions/pi-cwd-guard.json

Example:

{
  "allowedOutsideCwdPaths": [
    "/tmp",
    "/var/tmp",
    "~/shared-workspace",
    "../sibling-project"
  ],
  "allowedDestructiveBashPaths": [
    "/tmp/pi-web-video2"
  ]
}

Notes:

• Multiple paths are supported.
• Matching is recursive: allowing /tmp allows /tmp/foo/bar.txt.
• ~ expands to your home directory.
• Absolute paths are used as-is.
• Relative paths in project config resolve against the current working directory.
• Relative paths in global config resolve against ~/.pi/agent/extensions.
• Project and global path lists are merged independently.
• allowedOutsideCwdPaths only skips outside-cwd confirmation. It does not bypass hard-protected path blocks or destructive bash confirmation.
• allowedDestructiveBashPaths skips the destructive bash confirmation only for recognized rm commands when every static absolute or ~/... target is recursively covered.
• Relative, dynamic, or ambiguous targets, mixed allowed/disallowed targets, redirections on the rm segment, and unrelated destructive operations still require confirmation.
• Existing path ancestors are resolved through symlinks before applying an exemption. This remains a heuristic preflight check, not a sandbox or protection against filesystem races.

You can also inspect or update the config from Pi with the /cwd-guard command:

/cwd-guard
/cwd-guard show
/cwd-guard allow /tmp --project
/cwd-guard allow /tmp --global
/cwd-guard allow /tmp /var/tmp ~/shared-workspace --project
/cwd-guard allow "/tmp/my folder" --project
/cwd-guard allow-destructive /tmp/pi-web-video2 --project

Command notes:

• /cwd-guard opens an interactive menu for showing config or adding exceptions. Without UI, it displays the merged active configuration.
• /cwd-guard show displays the merged active configuration.
• Typing /cwd-guard in interactive mode autocompletes subcommands; both allow commands autocomplete --project / --global.
• allow <path...> --project|--global updates allowedOutsideCwdPaths.
• allow-destructive <path...> --project|--global updates allowedDestructiveBashPaths.
• Global updates write ~/.pi/agent/extensions/pi-cwd-guard.json and ask for confirmation first.
• Paths added by the command are written as absolute resolved paths.
• Command arguments support shell-style single quotes, double quotes, and backslash escapes for paths with spaces.

Hard-protected paths

write and edit are blocked for sensitive, vendor, or generated paths such as:

• .env, .env.*
• secrets/, .secrets/, credentials/, .credentials/
• .npmrc, .pypirc, id_rsa, id_ed25519, kubeconfig files
• common credential JSON files such as secrets.json, credentials.json, client_secret.json, service-account JSON files
• *.pem, *.key, *.p12, *.pfx
• node_modules/
• generated/build output dirs like dist/, build/, coverage/, .next/, .nuxt/, generated/

These are hard-blocked rather than confirmed.

Application configuration guidance

The extension adds semantic guidance asking the agent to get permission before changing actual application configuration, runtime configuration, or deployment configuration—including configured values, defaults, endpoints, feature flags, ports, or provider settings—unless the user's current request already explicitly authorizes that exact change.

Configuration is not classified from path or content patterns. A file, directory, or symbol containing config, settings, or env does not by itself require permission. Configuration UIs, models, schemas, validation, tests, documentation, and refactors are treated as ordinary application code. For example, editing src/features/settings/page.tsx or src/config/user-preferences.ts does not trigger a tool-level confirmation merely because of its path.

This policy is advisory because the agent can use task context to distinguish an actual configuration change from code implementing a configuration feature. Hard-protected credential and secret paths remain blocked, and the cwd and destructive-command checks remain enforced by tool hooks.

Permission prompt notifications

If pi-cmux is installed, pi-cwd-guard sends a best-effort cmux notification/status update whenever it opens a permission confirmation. This is optional and no-ops when pi-cmux is not present.

Common destructive bash confirmation

bash asks for confirmation before common destructive commands such as:

• recursive/forced rm
• sudo
• dangerous chmod
• recursive chown
• git reset --hard
• git clean -fd

This is intentionally heuristic and small. It does not parse shell scripts, inspect script files, or sandbox Python/Node.js/other scripts. Recognized forced or recursive rm commands skip confirmation when every static absolute or home-relative target is under an allowedDestructiveBashPaths entry. A compound command may precede the exempted rm only with recognized mkdir -p operations under the same allow-list. Commands with relative, dynamic, ambiguous, mixed, or symlink-escaping targets remain confirm-by-default. Other destructive patterns such as sudo and Git operations are never path-exempted.

The extension also adds advisory prompt guidance telling the agent to inspect both active merged exception lists before requesting permission. It identifies allowedOutsideCwdPaths as recursive exceptions for outside-cwd access, including covered relative file-tool paths after resolution against the cwd, and allowedDestructiveBashPaths as recursive exceptions for supported forced or recursive rm commands. Restrictions on relative, dynamic, ambiguous, or mixed targets apply to destructive rm exemptions, not normal outside-cwd path matching. The agent therefore does not ask solely because a covered access is outside the cwd or a covered recognized rm is destructive; uncovered scripted access and unrelated destructive commands still require confirmation.

Install

From npm:

pi install npm:pi-cwd-guard

From a local checkout:

pi install /absolute/path/to/pi-cwd-guard

Or test for one run:

pi -e /absolute/path/to/pi-cwd-guard

The package also includes a root index.ts shim, so direct extension-directory configuration such as "extensions": ["/absolute/path/to/pi-cwd-guard"] works too.

Compatibility

pi-cwd-guard uses Pi's extension API via a peer dependency and requires @earendil-works/pi-coding-agent 0.80.3 or newer.

Development

npm install
npm test
npm run typecheck
npm run pack:dry-run

Package manifest

This package exposes its extension through:

{
  "pi": {
    "extensions": ["./src/index.ts"]
  }
}