pi-agent-tick

Agent Tick support for Pi: remote human decisions, approval gates, and lifecycle status updates for coding-agent sessions.

This package replaces the generic ask_user experience with an Agent Tick-first tool named agent_tick_ask_user, while keeping a local Pi prompt and a compatibility ask_user alias.

What is Agent Tick?

Agent Tick is a human-in-the-loop control plane for agent work. It lets an agent send a focused decision, approval request, or status update to a user outside the terminal — for example in a phone or web UI — then wait for the user's response before continuing.

In this package, Agent Tick is used only as a decision/approval/status layer. It does not execute shell commands or tools remotely.

How answering works

When Agent Tick config is available, each agent_tick_ask_user prompt appears in two places at the same time:

1. the local Pi ask_user TUI on the machine running the agent
2. the Agent Tick app/web UI with the same question and choices

Answer from whichever place is convenient for that request. The first valid answer wins, and the other pending prompt is cancelled/abandoned. That means you can answer one decision from the terminal, the next from your phone, and switch back and forth per request.

What this package does

• Registers agent_tick_ask_user, a Pi tool for asking exactly one focused question.
• Shows the local Pi ask_user TUI and the Agent Tick app/web request simultaneously when agent-tick login config is available.
• Uses whichever side answers first, then cancels/abandons the other pending prompt.
• Sends single-select, multi-select, comments, and recommended-option flags to Agent Tick.
• Keeps a local overlay/inline Pi prompt so sessions still work without Agent Tick.
• Optionally gates risky bash tool calls with local and/or Agent Tick approval.
• Optionally sends lifecycle status updates such as working, waiting, blocked, done, or failed.
• Bundles an agent-tick-decision-gate skill for high-impact or ambiguous decisions.

Install

pi install npm:@self-deprecated/pi-agent-tick

For local development or unreleased changes:

pi install git:github.com/self-deprecated/pi-agent-tick

Run Agent Tick login to enable remote phone/web mirroring:

agent-tick login

If no Agent Tick config is found, the same tool still opens the local Pi prompt. If config is found, you get both the local prompt and the remote Agent Tick request for each question.

Quick example

Ask Pi to use agent_tick_ask_user at a decision boundary. A good call includes a short context summary and one focused question:

{
  "question": "Which deploy target should I use?",
  "context": "The branch has passed tests locally. Staging is reversible; production affects customers immediately.",
  "options": [
    { "title": "staging", "description": "Safer, reversible validation path", "flags": ["favorite", "safest"] },
    { "title": "production", "description": "Customer-facing deploy" }
  ],
  "allowFreeform": false,
  "choiceInteractionMode": "select-then-submit"
}

Tool names

Canonical tool:

• agent_tick_ask_user

Compatibility alias:

• ask_user

Installing this together with the original pi-ask-user package is not recommended because both provide an ask_user tool.

Agent Tick configuration

Agent Tick auth/config follows the Agent Tick CLI:

1. AGENT_TICK_CONFIG, or ~/.config/agent-tick/config.json
2. AGENT_TICK_SERVER and/or AGENT_TICK_TOKEN environment overrides

Useful environment variables:

Variable	Purpose
PI_AGENT_TICK_DISABLED=1	Disable remote Agent Tick mirroring even when config exists.
PI_AGENT_TICK_TIMEOUT_MS	Remote wait timeout. Defaults to unlimited (0).
PI_AGENT_TICK_CHOICE_INTERACTION_MODE	click-to-submit or select-then-submit.
PI_AGENT_TICK_OPTION_PLACEMENT	sticky-bottom or inline-after-content.
PI_AGENT_TICK_CONFIRM_BEFORE_SUBMIT	always/never or boolean-ish values.

Extension behavior configuration

Behavior config is separate from Agent Tick auth. It resolves in this order:

1. built-in defaults
2. global config: ~/.config/pi-agent-tick/config.json
3. project-local config: .pi/agent-tick.json
4. explicit config path: PI_AGENT_TICK_EXTENSION_CONFIG=/path/to/config.json

Project-local config overrides global config. Rule maps are keyed by ID, so a local config can disable or change one global rule without copying every rule.

Optional status updates

Status updates are best-effort and only send when Agent Tick config is present and status config is enabled.

{
  "status": {
    "enabled": true,
    "hooks": {
      "before_agent_start": { "send": true, "state": "working", "message": "task-summary" },
      "turn_end": { "send": false, "state": "working", "message": "none" },
      "agent_end": { "send": true, "state": "waiting", "message": "Finished; waiting" },
      "session_shutdown": { "send": false, "state": "done", "message": "none" }
    },
    "heartbeat": { "enabled": true, "intervalMs": 285000, "message": "Still working" }
  }
}

Optional bash approval gates

Sanctions are opt-in. By default there are no allow/deny rules and no command approval gate is applied.

Example: allow everything except matching risky commands, which require approval:

{
  "sanctions": {
    "enabled": true,
    "policy": "allow-by-default",
    "tools": {
      "bash": {
        "deny": {
          "rm-rf": {
            "command": "rm",
            "argsRegex": "(^|\\s)-[A-Za-z]*r[A-Za-z]*f",
            "riskClass": "destructive-filesystem",
            "reason": "recursive forced remove"
          },
          "push": {
            "commandRegex": "^(git|jj)$",
            "argsRegex": "\\bpush\\b",
            "riskClass": "vcs-push",
            "reason": "VCS push"
          }
        }
      }
    }
  }
}

Example: require approval by default, but allow known-safe commands:

{
  "sanctions": {
    "enabled": true,
    "policy": "approve-by-default",
    "tools": {
      "bash": {
        "allow": {
          "jj-status": { "command": "jj", "argsRegex": "^st(atus)?$" },
          "safe-tests": { "commandRegex": "^(bun|npm)$", "argsRegex": "\\btest\\b" }
        }
      }
    }
  }
}

If allow and deny rules both match, deny wins. Remote approval request bodies are redacted before disclosure. Agent Tick returns only the approval decision; Pi still owns local tool execution.

agent_tick_ask_user parameters

Parameter	Type	Default	Description
question	string	required	The one focused question to ask.
context	string?	—	Short summary of relevant findings or trade-offs.
options	(string | {title, description?, flags?})[]?	[]	Multiple-choice options. Use flags: ["favorite"] for the recommended option.
allowMultiple	boolean?	false	Enable multi-select mode.
allowFreeform	boolean?	true	Add a freeform answer path.
allowComment	boolean?	false	Let the user attach optional extra context to a selection.
displayMode	"overlay" | "inline"?	env or "overlay"	Local Pi rendering mode.
overlayToggleKey	string?	env or "alt+o"	Hide/show local overlay while it is open. Pass "off" to disable.
commentToggleKey	string?	env or "ctrl+g"	Toggle optional comment row. Pass "off" to disable.
timeout	number?	—	Auto-dismiss local UI and use the same remote wait timeout.
choiceInteractionMode	"click-to-submit" | "select-then-submit"?	env or "click-to-submit"	Remote Agent Tick choice behavior.
optionPlacement	"sticky-bottom" | "inline-after-content"?	env or "inline-after-content"	Remote Agent Tick option placement.
confirmBeforeSubmit	boolean?	env or true	Ask Agent Tick to confirm direct clickable submissions.

Attribution

This package is based on Enzo Lucchesi's edlsh/pi-ask-user, an MIT-licensed Pi package for interactive prompts. The local Pi prompt implementation remains derived from that project, and the original copyright/license notice is preserved in LICENSE.