my-pi/pi-permission-system/docs/troubleshooting.md

Troubleshooting

Common Issues

Problem	Cause	Solution
Config not applied (everything asks)	File not found or parse error	Verify the global policy at config/pi-permission-policy.jsonc inside the installed bundle; check JSONC syntax
Per-agent override not applied	Frontmatter parsing issue	Ensure --- delimiters at file top; keep YAML simple; restart session
Tool blocked as unregistered	Unknown tool name	Server tools arrive as mcp__<server>__<tool> under Pi's built-in MCP (check /mcp); a unified mcp proxy tool uses { "tool": "server:tool" }
/skill:<name> blocked	Deny policy or confirmation unavailable	Check merged skill policy (global/project/agent layers). ask still requires UI or forwarded confirmation.
External file path blocked	external_directory is ask without UI or deny	Allow/ask the permission or keep file tools inside the active working directory.
Spurious external-path prompt for cd <subdir> && grep … ../path	Relative path was resolved against cwd instead of the cd target	Fixed in current version — paths after a leading cd <subdir> && are resolved against the cd target, matching actual shell behavior.
Permission prompt is too verbose	Generic extension tool input is large	Built-in file tools are summarized automatically; third-party tools are capped to a bounded one-line JSON preview.
A file write keeps prompting despite a session grant or yolo	The target is in protectedWrites	Working as designed — protected writes are human-only and never take a session grant. Remove the entry from protectedWrites in config/pi-permission-hard-guards.jsonc to lift it.
A file write is denied without any prompt	protectedWrites target, no confirmation UI (headless or subagent relay)	Working as designed — a human-only ask cannot be answered without a local UI. Run the write from an interactive session instead.

Diagnostic Logging

Enable "debugLog": true in your config to write verbose diagnostics to logs/pi-permission-system-debug.jsonl.

On every session start, the extension emits a config.resolved entry to both logs listing the resolved config paths and whether each exists. This makes it easy to verify which files the extension actually loaded:

{
  "event": "config.resolved",
  "globalConfigPath": "/…/bundle/config/pi-permission-policy.jsonc",
  "globalConfigExists": true,
  "agentsDir": "/…/.pi/agent/agents",
  "agentsDirExists": true,
  "projectAgentsDir": "/…/my-project/.pi/agents",
  "projectAgentsDirExists": false
}

Threat Model

Goal: Enforce policy at the host level, not the model level.

What this stops:

• Agent calling tools it shouldn't use (e.g., write, dangerous bash)
• Tool switching attempts (calling non-existent tool names)
• Accidental escalation via skill loading
• Unapproved path-bearing tool access outside the active working directory when external_directory is ask or deny

Limitations:

• If a dangerous action is possible via an allowed tool, policy must explicitly restrict it
• This is a permission decision layer, not a sandbox — for true isolation see Agent Sandboxes
• The review log records bash command strings unredacted. Log files are created owner-only (0600), and values bound to a sensitive key name (authorization, token, password, …) are masked — but a secret embedded in a command string is not. Review-log values are shortened at reviewLogFieldMaxWidth (1000 characters by default), which bounds the file's growth but is a length cap, not redaction. See Log file sensitivity and ADR 0010.