Skip to content

bug(agents): YAML tools frontmatter leaves Gentle subagents without filesystem tools #62

Open
#1144
Open
bug(agents): YAML tools frontmatter leaves Gentle subagents without filesystem tools#62
#1144
Labels
bugSomething isn't workingstatus:approvedIssue approved by maintainer; PR may be openedtype:bugBug fix

Description

@danielnunez-beep
danielnunez-beep
opened on Jul 2, 2026

Bug Description

gentle-pi currently ships package agent definitions with tools declared as YAML block lists, but pi-subagents@0.32.0 appears to parse agent tools as a comma-separated scalar string.

In a live Pi session this caused Gentle 4R agents such as review-reliability and review-risk to start with only:

functions.intercom, functions.contact_supervisor, multi_tool_use.parallel

They did not receive read, grep, glob, or bash, so they could not inspect files/diffs and reported that they were blocked. The builtin reviewer agent worked in the same session because its bundled frontmatter uses scalar comma-separated tools.

Steps to Reproduce

  1. Install/use gentle-pi@0.11.1 with pi-subagents@0.32.0.
  2. Run a Gentle 4R/custom agent, for example review-reliability, via subagent.
  3. Ask the child to report its available tools or inspect a repo diff.
  4. Compare with builtin reviewer in the same session.

Observed canary from the same parent session:

review-reliability: available_tools: functions.intercom, functions.contact_supervisor, multi_tool_use.parallel
review-risk:        available_tools: functions.intercom, functions.contact_supervisor, multi_tool_use.parallel
reviewer:           available_tools: functions.read, functions.grep, functions.find, functions.ls, functions.bash, functions.edit, functions.write, functions.intercom, functions.contact_supervisor, multi_tool_use.parallel

Expected Behavior

Gentle package agents that declare:

tools:
  - read
  - grep
  - glob
  - bash

should receive those tools in the child Pi session.

Actual Behavior

The child session receives only intercom/supervisor tools. The declared filesystem/shell tools are not available, so read-only review agents cannot review.

Evidence

Current gentle-pi uses YAML block-list tools, for example:

gentle-pi tests explicitly require YAML lists and reject comma-separated tools:

But pi-subagents@0.32.0 frontmatter loading stores block values as strings and later splits frontmatter.tools only by comma:

pi-subagents docs also show comma-separated scalar tools:

Expected Fix Direction

Either direction would work, but the ecosystem needs one consistent contract:

  1. Update pi-subagents to parse YAML block-list tools into individual tool names; or
  2. Update gentle-pi packaged agents/tests to use comma-separated scalar tools until YAML arrays are supported by the runtime.

Given the current pi-subagents docs and runtime behavior, the fastest compatibility fix in gentle-pi may be to emit comma-separated tools in packaged agent frontmatter.

Operating System

macOS

Agent / Client

Pi / el Gentleman with pi-subagents

Shell

bash

Relevant Versions

gentle-pi: 0.11.1
pi-subagents: 0.32.0

Pre-flight Checks

  • I searched existing issues/PRs for duplicates (tools frontmatter, subagent tools, only intercom, contact_supervisor, review-reliability).
  • I understand this issue needs maintainer review/approval before opening a PR.

Activity

  1. danielgap commented on Jul 6, 2026

    @danielgap
    danielgap
    on Jul 6, 2026
    Contributor

    Additional current-session evidence: this is still reproducible with the latest active Pi extension install, not only the older versions in the original report.

    Environment checked from /home/dseo/.pi/agent/npm:

    @earendil-works/pi-coding-agent 0.80.3
pi-subagents 0.33.1
gentle-pi 0.11.3
pi-intercom 0.6.0
gentle-engram 0.1.9

    npm view confirms pi-subagents@0.33.1, gentle-pi@0.11.3, and @earendil-works/pi-coding-agent@0.80.3 are latest at the time of testing.

    Observed behavior in /home/dseo/clavahachas:

    • review-reliability, review-readability, and review-resilience launched through subagent(...) repeatedly reported they only had intercom/contact_supervisor tools and could not read files or write their requested audit artifacts.
    • Builtin scout and builtin reviewer worked in the same parent session and successfully read the repo and wrote artifacts.
    • subagent({ action: "get", agent: "review-reliability" }) displays the intended tools as read, grep, glob, bash, so discovery sees the frontmatter but runtime provisioning still fails for the YAML-list form.

    Local root-cause confirmation:

    • Gentle user agent files installed at ~/.pi/agent/agents/review-*.md, sdd-*.md, and jd-*.md use YAML-list syntax:
    tools:
  - read
  - grep
  - glob
  - bash
    • Active pi-subagents@0.33.1 still parses frontmatter.tools via .split(",") in src/agents/agents.ts, while parseFrontmatter() stores YAML block values as strings. That means a block-list value can become one malformed tool name containing newlines instead of individual tools.
    • buildPiArgs() then forwards the malformed allowlist to pi --tools, leaving only bridge tools visible in the child session.

    One extra compatibility note: several Gentle agents declare glob, while Pi help currently documents find in examples (pi --tools read,grep,find,ls). If glob is no longer a builtin in this runtime, the compatibility fix should probably normalize these agent allowlists to find as well.

    Workaround confirmed in practice: avoid the Gentle review-* agents for now and use builtin scout / builtin reviewer, whose frontmatter uses comma-separated scalar tools and receives filesystem tools correctly.

  2. jjeg1979
    added a commit that references this issue on Aug 14, 2026

    fix(pi): align review and Judgment Day tool allowlists

    de7e335

  3. barbatdev commented on Aug 15, 2026

    @barbatdev
    barbatdev
    on Aug 15, 2026
    SponsorContributor

    Approved. The report has two independent reproductions, and there is enough evidence to act.

    There are two separate causes behind the same user-visible failure: YAML block-list parsing in pi-subagents, and packaged agents declaring unavailable glob/webfetch tools. PR #289 addresses only the second one.

    Keep #62 open after #289 merges. The issue is resolved only when the YAML parsing path is fixed and covered by a named regression test.

  4. barbatdev
    added
    status:approvedIssue approved by maintainer; PR may be opened
    on Aug 15, 2026

  5. danielgap commented on Aug 25, 2026

    @danielgap
    danielgap
    on Aug 25, 2026
    Contributor

    Closing the loop on the approval condition ("resolved only when the YAML parsing path is fixed and covered by a named regression test") — taking this final slice now.

    Parsing path status: fixed upstream. pi-subagents 0.35.0 (2026-07-17) added parseFrontmatterList, accepting newline block lists for tools while preserving comma syntax (upstream nicobailon/pi-subagents#507, thanks to @klopket). Verified today by running the 0.35.0/0.56.0 algorithm verbatim against all 22 packaged agents on current main: every agent parses to its declared tool allowlist (including the "*": false deny-all shape on review/jd agents and the find-for-discovery fix from #289). The 0.34.0 comma-only split that produced single garbage tokens is gone.

    Proposed slice (the named regression test): a new tests/agent-tool-parsing-contract.test.ts that vendors the exact upstream parsing contract (parseFrontmatterList + splitToolList, pinned by comment to pi-subagents >= 0.35.0 / upstream #507) and asserts, for every packaged agent, that:

    1. the YAML block parses to non-empty clean tokens (no collapsed newline tokens — the bug(agents): YAML tools frontmatter leaves Gentle subagents without filesystem tools #62 failure signature),
    2. filesystem tools survive (read present on all 22 agents),
    3. the "*": false deny-all marker does not swallow the tools that follow it,
    4. both forms (YAML block and comma scalar) parse to the same partition, mcp: entries included.

    If pi-subagents ever regresses to comma-only, or gentle-pi ships a YAML shape the parser collapses, this suite fails. PR incoming; no code/runtime change.

  6. dnlrsls
    added
    type:bugBug fix
    bugSomething isn't working
    on Oct 1, 2026

  7. MataM15 commented on Oct 9, 2026

    @MataM15
    MataM15
    on Oct 9, 2026

    Checked this against current main (dafdd2b28, gentle-pi 4.0.0) with a source read, not a live session.

    The parsing side looks fixed in the Gentle Agents runtime that replaced pi-subagents (#609):

    • lib/agents-config.ts (parseFrontmatter) collects YAML block-list entries into arrays, and parseTools keeps them as individual names.
    • lib/agents-runner.ts forwards them to the child as a comma-separated --tools value.
    • All 10 agents currently shipped in assets/agents/ declare read as a separate list entry.
    • Existing coverage: tests/agents-config.test.ts ("parseFrontmatter reads scalars, inline lists, and block lists") and tests/agents-runner.test.ts (asserts --tools read,grep,subagent_parent_message).

    What is still missing is the approval condition from the triage: the named packaged-agent regression (tests/agent-tool-parsing-contract.test.ts) is not on main. #429 was closed without merging and #1144 is still open.

    So the remaining work seems to be landing #1144 (or deciding the existing tests above are enough), after which this can probably be closed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingstatus:approvedIssue approved by maintainer; PR may be openedtype:bugBug fix

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions