stacklok / stacklok/mecatl

feat(subagent): add opt-in bounded discovery profile

Open
#691 0 comments 0 reactions 1 assignee View on GitHub

@JAORMX is already working on this.

Since Sep 7, 2026.

Dominant language
Go
Stars
152
Forks
16
Avg merge
14h 48m
Merged PRs (30d)
536

Description

Problem

A coding subagent can burn its context budget before editing by issuing several unbounded full-file Read calls in parallel. Prompt-only guidance is insufficient: the worker may interpret a list of relevant files as a request to read each entire file.

Proposal

Add an opt-in Subagent discovery profile that enforces context-efficient exploration at the tool boundary:

  • require Read calls to specify offset and limit, with a deliberate escape hatch for explicitly approved small/full-file reads;
  • cap lines and/or bytes returned per read;
  • serialize reads during discovery so several large tool results cannot land in one turn;
  • retain Glob, Grep, and targeted Edit;
  • return an actionable rejection directing the child to Grep first and then make a bounded read;
  • expose per-turn read/result byte and token accounting in the child transcript or diagnostics.

The profile should be opt-in, not a global default: full-file review and small files are legitimate workflows.

Motivation

A real delegated refactor consumed 274,477 input tokens and only 561 output tokens in one turn after five broad reads, then produced no implementation. The main failure was tool-result ingestion, not reasoning or output.

Acceptance

  • A bounded-profile child cannot issue an unbounded Read or several concurrent reads.
  • Rejections explain the bounded-read workflow.
  • The profile does not change default Subagent behavior.
  • Tests cover the escape hatch and read-volume telemetry.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.