`overstory-guard.ts` extension affects standalone Pi sessions instead of being scoped to Overstory worktrees.

[RogerNavelsaker]

Steps to reproduce

1. Start a standalone pi session in a repository where Overstory has previously spawned an
   agent.
2. Ensure the agent role in the generated .pi/extensions/overstory-guard.ts is set to a
   read-only role (e.g., coordinator).
3. Attempt to run a write tool (edit, write) or a restricted bash command (echo >, mv).

Expected behavior

The guard should only apply to agents running inside an Overstory-managed worktree (e.g.,
.overstory/worktrees/...). Standalone sessions in the repository root should remain unblocked.

Actual behavior

The guard intercepts all tool_call events for the pi agent because it is placed in the
project-wide .pi/extensions/ directory, causing persistent "coordinator agents cannot modify
files" errors in standalone sessions.

overstory version

0.9.1

Bun version

1.3.10

Operating system

Linux (CachyOS/Arch, Kernel 6.19.7)

[RogerNavelsaker]

Potential Fix

The guard should verify it is running in an Overstory context before enforcing blocks. We can do this by checking for an Overstory-specific environment variable or validating that the current working directory is inside an Overstory worktree.

Proposed change to overstory-guard.ts template:

  // Inside the tool_call handler
  pi.on("tool_call", async (event) => {
      // Only enforce blocks if we are explicitly in an Overstory session
      const isOverstorySession = process.env.OVERSTORY_AGENT_NAME ||
                                process.cwd().includes(".overstory/worktrees/");

      if (!isOverstorySession) return; // Allow everything for standalone sessions

      // ... existing guard logic ...
  });

Additionally, overstory-guard.ts should be added to the repository's .gitignore by default so it doesn't accidentally get committed to main and affect other users/environments.

---

[RogerNavelsaker]

I think the fix here should be to scope behavior by spawned session type, instead of writing a project-wide overstory-guard.ts file and then trying to move it in/out of the way.

In our os-eco-pi-extension prototype, the extension already has the right shape for this:

• it detects Overstory-managed sessions with env/cwd checks
• it no-ops the guard path for standalone sessions
• it applies tool restrictions only for Overstory sessions

Relevant pieces:

• session detection and current guard-file rename logic:
  • os-eco-pi-extension/index.ts
• runtime gating of tool restrictions:
  • os-eco-pi-extension/index.ts
• Overstory-only readiness widget/marker:
  • os-eco-pi-extension/workflow-status.ts

What this suggests upstream is:

1. Stop using a project-global guard file as the enforcement mechanism

The problem in #117 is really that .pi/extensions/overstory-guard.ts is global to the repo, while the intended behavior is session-local.

That means the control point is in the wrong place.

Instead of:

• write/remove/rename overstory-guard.ts under .pi/extensions/

prefer:

• load one extension package
• have it branch behavior based on session metadata provided at spawn time

2. Pass explicit session type into Pi-spawned sessions

Something like:

OVERSTORY_SESSION_KIND=standalone|orchestrator|coordinator|monitor|worker
OVERSTORY_AGENT_NAME=...
OVERSTORY_CAPABILITY=...
OVERSTORY_WORKTREE_PATH=...
OVERSTORY_PROJECT_ROOT=...

Then the extension can behave deterministically per session.

3. Make extension behavior session-type aware

Example policy split:

• standalone
  • no Overstory guards
  • no write/path restrictions
  • no task ownership enforcement
  • no mail/agent logging requirements
• orchestrator / coordinator / monitor
  • Overstory delegation rules enabled
  • interactive-tool restrictions enabled
  • coordination-safe shell subset allowed
  • no project-global side effects
• worker
  • full path-boundary enforcement
  • write restrictions based on capability
  • task ownership checks
  • explicit ready marker if needed for runtime readiness

4. Keep the extension loaded, but make its effects conditional

This is the key difference:

• extension installation can be repo-level
• extension behavior must be session-level

That avoids the current failure mode where a standalone Pi session in the repo root inherits Overstory restrictions just because an earlier Overstory run dropped a file into .pi/extensions/.

5. This also aligns with the ready-marker direction from #116

If Pi integration moves toward:

• explicit extension-owned readiness markers
• session-type-aware behavior
• no brittle UI parsing
• no project-global guard file mutation

then Overstory core becomes simpler:

• spawn session with metadata
• extension decides how to behave
• core waits for explicit signals instead of inferring from repo state

In practice, I think this means:

• remove pi-guard.ts / pi-guard.test.ts from core Overstory
• stop generating repo-local guard files
• move Overstory-specific Pi behavior into a dedicated extension package
• make that extension branch on explicit session kind/capability metadata

[jayminwest]

Closing as duplicate of #116. Both issues target the Pi runtime, are from the same author, and converge on the same architectural direction: remove core-generated guards, switch to an external Pi extension, and use explicit ready markers. PR #129 addresses both #116 and #117 in a single implementation. Tracking the unified Pi runtime overhaul under #116.