pi-ask-mode

A shareable pi package that adds ask mode.

Ask mode is a read-only investigative mode for analysis, debugging, exploration, and answering questions without using file mutation tools or interactive UI prompt tools.

What ask mode enables

When ask mode is on, pi uses these tools:

• read
• bash
• grep
• find
• ls
• subagent if it exists in the current pi environment

What ask mode blocks

Ask mode blocks these tools:

• edit
• write
• question
• questionnaire
• askUserQuestion (if another extension registers it)

It also restricts bash to read-only / investigative commands.

Examples of allowed shell usage:

• ls, tree, pwd
• cat, head, tail, file, stat
• grep, rg, find, fd
• git status, git log, git diff, git show, git rev-parse
• git branch --show-current, git branch --list, git remote -v, git remote show origin
• npm list, npm info, npm outdated, npm audit --json
• env, printenv, uname, whoami, ps, uptime
• jq, awk, sed -n
• help, man, and CLI help/version commands like foo --help, foo help, foo --version
• broadly, arbitrary CLIs for read-only inspection like gh pr view, terraform plan, or kubectl get ...
• curl and wget -O - for read-only fetching

Examples of blocked shell usage:

• file mutation like rm, mv, cp, mkdir, touch
• editors like vim, nano, code
• package installs like npm install, pnpm add, brew install
• package mutation like npm audit fix
• git writes like git add, git commit, git push, git branch feature-x, git remote add origin ...
• common mutating CLI actions like gh repo create, terraform apply, kubectl apply, docker run
• output redirection like > or >>
• command substitution like `...` or $(...)
• privilege/system actions like sudo, kill, shutdown

Install

Global install

pi install /absolute/path/to/pi-ask-mode

When published, users can install it globally with:

pi install npm:pi-ask-mode

or:

pi install git:github.com/<owner>/pi-ask-mode

Usage

Slash command

/ask

Toggle ask mode on or off.

You can also use:

/ask on
/ask off
/ask status

Start pi directly in ask mode

pi --ask

Behavior

When ask mode is enabled:

• pi switches active tools to read,bash,grep,find,ls plus subagent when available
• edit, write, question, questionnaire, and askUserQuestion are blocked defensively at tool-call time
• bash is limited to read-only / investigative commands
• subagent is allowed only for read-only context gathering, inspection, search, analysis, and summarization
• subagent management is limited to read-only actions like list and get
• subagent worktrees and output-file writes are blocked
• the model is instructed to ask the user directly in normal chat instead of using UI prompt tools
• if pi starts with --ask, ask mode captures the current tool selection so /ask off can restore it later

Plan mode compatibility

This package is designed to play reasonably well with plan-mode style extensions.

Switching from plan mode to ask mode

If a compatible plan-mode extension stores state in either:

• plan-mode
• pi-constell-plan-state

then running:

/ask

will:

• enable ask mode
• write a disabled plan-mode state entry
• reload the runtime so the other mode shuts off cleanly

This avoids plan-mode UI prompts continuing to appear while ask mode is active.

Switching from ask mode to plan mode

Running:

/plan

from a compatible plan-mode extension should switch tools away from ask mode. On the next prompt, pi-ask-mode detects that another mode has taken over and disables ask mode state.

Testing

Run the bash safety tests with:

npm test

Suggested manual smoke test:

1. Launch pi with this package loaded.
2. Run /ask on, /ask status, and /ask off.
3. In ask mode, verify git diff is allowed and git commit -m "test" is blocked.
4. If subagent is available, verify a read-only task like Analyze the auth flow and summarize the touched files is allowed, while a mutating task like Implement the fix is blocked.
5. If you use a compatible /plan extension, switch between /plan and /ask once in each direction.

Important note

This is not a perfect sandbox.

Even with a read-only bash allowlist, this package is only an extension-level policy layer. It is designed to keep the agent in an investigative, non-mutating workflow, but it does not replace OS-level sandboxing.

If you need stronger guarantees, run pi inside a sandbox, container, VM, or other restricted environment.