@ordewell/core 0.8.1 → 0.9.1

package/dist/{IRunner-XVUddYVX.d.mts → IRunner-D6YfbmHn.d.mts}

@@ -2,6 +2,361 @@ import { ChildProcess } from 'child_process';
 import { ao as UsageRecord, a8 as SubagentOutcome, W as RunnerId, ag as TaskSkillSnapshot } from './Task-1Q19y7sZ.mjs';
 import { z } from 'zod/v4';
 
+/**
+ * The planner's standing approvals (ADR-0026): what runs without asking
+ * anyone, under every approval mode.
+ *
+ * One entry is one of:
+ *
+ *   - a **command rule**, `gh issue list` or `gcloud * * list`: the binary,
+ *     then words matched against the command's leading arguments, the ones
+ *     before its first flag. A command whose leading words match the rule's
+ *     runs, whatever arguments follow — but the rule must spell out at least
+ *     the words the command's approval scope holds (ADR-0008, T1), so
+ *     `az group` never covers `az group delete`, and a one-word read takes a
+ *     `*` for its argument (`kubectl get *`). `*` stands for one word, and
+ *     inside a word for any run of characters (`describe-*`). An entry equal
+ *     to a scope also matches that scope, as pre-approved scopes always did.
+ *   - an **MCP tool rule**, `mcp:find-*`: a glob over the tool's own name,
+ *     without the server, case-insensitive.
+ *   - a **scope pattern**, anything starting with `/`, `~`, `http://`,
+ *     `https://`, `web_search:`, `mcp__`, `mcp-server:` or a drive letter: matched against an approval's
+ *     scope as ADR-0008 always matched pre-approved entries, `*` matching any
+ *     run of characters.
+ *
+ * A leading `!` excludes instead, and an exclusion wins over every rule. A
+ * command exclusion's words are looked for anywhere among the arguments, in
+ * order, flags included and case ignored, so `!kubectl *secret*` and
+ * `!* --endpoint*` hold wherever the word appears; a lone short flag (`-s`)
+ * also holds inside a bundle (`-As`, `-shost`). `*` as its binary covers
+ * every command.
+ */
+/** The words a command rule is matched against: a lexed segment's binary and arguments. */
+interface CommandWords {
+    binary: string;
+    args: readonly string[];
+    /** How many leading arguments the command's approval scope holds; a rule must cover at least that many. */
+    scopeWords?: number;
+}
+interface RuleWord {
+    matches: (word: string) => boolean;
+    wildcard: boolean;
+}
+interface CommandRule {
+    text: string;
+    binary: string;
+    words: RuleWord[];
+}
+interface PlannerAllowlist {
+    commands: CommandRule[];
+    commandExclusions: CommandRule[];
+    tools: RegExp[];
+    toolExclusions: RegExp[];
+    scopes: RegExp[];
+    scopeExclusions: RegExp[];
+}
+declare function parseAllowlist(entries: readonly string[]): PlannerAllowlist;
+/** The rule that lets this command run unasked, or undefined when none does or an exclusion holds. */
+declare function commandAllowedBy(list: PlannerAllowlist, command: CommandWords): string | undefined;
+/** Whether an MCP tool, by its own name without the server, runs unasked. */
+declare function toolAllowed(list: PlannerAllowlist, tool: string): boolean;
+/** Whether an approval scope — a directory, an origin, a tool's full name — is pre-approved. */
+declare function scopeAllowed(list: PlannerAllowlist, scope: string): boolean;
+/**
+ * Read-only command families that are safe to run unasked: they read, never
+ * write a file or change a resource, and need no argument that runs code.
+ * Absent on purpose: commands that run the repository's own code (test
+ * runners, builds, package scripts, a package manager the repository pins or
+ * extends — on an untrusted repository someone else wrote that code), commands
+ * a repository's own config can point at another endpoint with the user's
+ * credentials (`.npmrc`, `.sentryclirc`, a Terraform or Pulumi backend), and
+ * commands whose usual output is a secret.
+ */
+declare const DEFAULT_PLANNER_ALLOWLIST: readonly string[];
+
+/**
+ * Which interpreter runs the planner's `bash` tool, and in which language.
+ *
+ * `AUTO_COMMANDS` — the read-only tier that runs with no prompt — is `ls`, `cat`,
+ * `wc`, `head`, `tail`, `du`, `df`, `file`, `sort`, `uniq`, `basename`, `find`,
+ * `grep`. That set is POSIX, and passing it to `shell: true` on Windows means
+ * cmd.exe, where most of those names do not exist and `find` is an unrelated
+ * program that returns plausible wrong output instead of an error. The planner's
+ * whole research surface degraded to guessing, quietly.
+ *
+ * Rather than write a Windows dialect of every research command — a second
+ * behavior to keep in step forever — this finds a POSIX shell to run the
+ * existing ones in. Git for Windows ships a full one, and git is already a
+ * prerequisite for everything Ordewell does, so in practice it is there. Failing
+ * that, cmd.exe is used and the classifier is told so, because the one thing
+ * that must never happen is classifying a command in one language and running it
+ * in another: `commandPolicy` reads {@link ResearchShell.dialect} for exactly
+ * that reason.
+ *
+ * POSIX resolves to `{ file: null }`, meaning "use `shell: true`" — byte for
+ * byte what the adapters did before this module existed.
+ *
+ * Windows paths are built with `path.win32` explicitly, not the host-flavoured
+ * `path`, so the probe is the same on a Windows host as it is under a Linux
+ * test runner.
+ */
+type ShellDialect = 'posix' | 'cmd';
+interface ResearchShell {
+    /**
+     * Executable that takes a command string, or null to use the host default
+     * via `shell: true`.
+     */
+    file: string | null;
+    /** Arguments preceding the command string. */
+    args: string[];
+    /** The language the command string will be interpreted in. */
+    dialect: ShellDialect;
+    /**
+     * Directory holding this shell's POSIX utilities, when it brings its own.
+     * Prepended to PATH for the search subprocesses (`grep`, `tree`) that
+     * `execFile` starts without a shell, so they resolve too.
+     */
+    utilsDir: string | null;
+}
+interface ResearchShellDeps {
+    platform?: NodeJS.Platform;
+    exists?: (candidate: string) => boolean;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * The shell the planner's `bash` tool should use on this host. Resolved once per
+ * process — the answer cannot change while Ordewell runs, and the probe costs a
+ * handful of `stat` calls.
+ */
+declare function resolveResearchShell(deps?: ResearchShellDeps): ResearchShell;
+/** Test seam: drop the per-process cache so the next call re-probes. */
+declare function clearResearchShellCache(): void;
+/**
+ * PATH for the search subprocesses the adapters start without a shell, with the
+ * research shell's own utilities in front. Without this, `grep` — the fallback
+ * when ripgrep is absent — is unresolvable on a Windows box even when a
+ * perfectly good `grep.exe` sits in the Git tree beside the shell.
+ */
+declare function researchToolsPath(shell: ResearchShell, basePath: string | undefined): string;
+/**
+ * A message explaining a degraded research surface, or null when there is
+ * nothing to explain. Surfaced by the adapters on the first refused command so
+ * the limitation is visible rather than inferred from bad answers.
+ */
+declare function researchShellWarning(shell: ResearchShell): string | null;
+
+/**
+ * Tiered classification for the planner's `bash` tool.
+ *
+ * The planner is a read-only researcher: it never edits files, and the runners
+ * do the real work. But research legitimately means running things — querying a
+ * cloud control plane (`az`, `gh`), reproducing a failure (`npm test`), or
+ * shaping output (`jq`). The old allowlist refused all of that, so the model's
+ * only escape was to guess.
+ *
+ * Three tiers replace the flat allowlist:
+ *
+ *   auto    read-only inspection — runs with no prompt (the historical list)
+ *   ask     anything else that is not obviously destructive — one approval,
+ *           remembered for the rest of the session at `scope` granularity
+ *   refuse  writes, privilege escalation, and anything that would smuggle
+ *           arbitrary code past this classifier — never runs, never prompts
+ *
+ * `refuse` is deliberately not promptable. A planner that can `rm` is a planner
+ * that can silently break the workspace it was asked to reason about, and the
+ * architecture already says mutation belongs to the runners.
+ *
+ * Classification walks every segment of the command line (pipes, `&&`, `;`, and
+ * command substitution) rather than matching substrings against the raw string.
+ * The old substring denylist both over-matched (`ls docs/removed` tripped `rm`)
+ * and under-matched (`$(rm -rf /)` was invisible once chaining was allowed).
+ *
+ * A segment is classified by the command that will actually execute, not by the
+ * name at the front of it: wrappers are unwrapped first, recursively, so
+ * `timeout 10 env nice rm -rf x` is an `rm`. See {@link WRAPPER_FAMILY}. A
+ * runner that feeds its command arguments nobody can see is unwrapped the same
+ * way but never runs unprompted ({@link XARGS_TARGETS}), and one that hands its
+ * command to a shell is refused ({@link REFUSED_RUNNERS}).
+ *
+ * A permitted binary is permitted with the flags it is known to be read-only
+ * with, not with any flag at all: several of them will run a helper program or
+ * write a file when asked to, so `auto` is a per-binary flag allowlist and an
+ * unrecognised flag is refused. See {@link FLAG_POLICY}.
+ *
+ * The lexer is dialect-aware, because the interpreter that will actually run
+ * the command decides what the tokens are, and getting that wrong is not a
+ * cosmetic error here — it is the difference between classifying what runs and
+ * classifying something else. See {@link Dialect}.
+ */
+
+/**
+ * `env` is deliberately absent. Given a command it is a wrapper, classified by
+ * what it actually runs (see {@link WRAPPER_FAMILY}); given none it prints the
+ * whole process environment — provider credentials included — into the research
+ * log, which is a disclosure the developer should get to see coming.
+ *
+ * Membership here is necessary but not sufficient: every name in this list also
+ * declares the flags it is read-only with in {@link FLAG_POLICY}.
+ */
+declare const AUTO_COMMANDS: string[];
+/**
+ * `ls-remote` is deliberately absent, and it is the one entry here that is
+ * read-only against the repository. It reaches the network: it contacts
+ * whatever host the named remote or URL resolves to, which routes around the
+ * web fetcher's per-origin approval and its request-forgery guard. So it
+ * prompts rather than running silently.
+ *
+ * Prompting only became the right answer once {@link scopeFor} widened. Under
+ * the old scope it would have been remembered as `git ls-remote`, so one
+ * approval of the workspace's own remote would have authorised a listing
+ * against any host at all — which is the same hole with an approval dialog in
+ * front of it. The scope now carries the destination.
+ */
+declare const GIT_READONLY_SUBCOMMANDS: string[];
+/**
+ * Never runs, with or without approval.
+ *
+ * The `cmd.exe` builtins at the end matter as much as the POSIX names above
+ * them. `del`, `rd`, `move`, and friends mutate exactly what `rm` and `mv` do,
+ * and on Windows they are what a model reaches for — so without them the whole
+ * refusal tier was bypassable on that platform by writing the command the way
+ * the platform spells it. Listed unconditionally rather than per-platform: a
+ * POSIX box has no `del` to refuse, so the extra names cost nothing there.
+ */
+declare const REFUSED_COMMANDS: string[];
+/**
+ * Options threaded through classification.
+ *
+ * `dialect` is keyed to the interpreter rather than the OS on purpose: a Windows
+ * host that has Git Bash runs the planner's commands in a POSIX shell (see
+ * {@link resolveResearchShell}), and classifying those under cmd.exe rules
+ * would be the same mismatch in the other direction. Callers pass the dialect of
+ * the shell they are actually going to use; omitting it falls back to the host
+ * default.
+ */
+interface CommandPolicyOptions {
+    dialect?: ShellDialect;
+    /** Only flags generated from vetted DNS answers by BaseFileSystem, never caller input. */
+    trustedWebResolves?: ReadonlySet<string>;
+    autonomous?: boolean;
+    approvalMode?: 'ask' | 'allow' | 'deny';
+    /**
+     * `CDPATH` is set in the environment the command will run in. A relative
+     * `cd` may then land in a directory the command line never names, so `cd`
+     * stops being navigation the classifier can follow.
+     */
+    cdpathSet?: boolean;
+    /** The planner's standing approvals (ADR-0026); an `ask` command they cover carries {@link CommandClassification.allowedBy}. */
+    allow?: PlannerAllowlist;
+}
+type CommandTier = 'auto' | 'ask' | 'refuse';
+interface CommandClassification {
+    tier: CommandTier;
+    /** A human must approve this invocation even when its origin was already granted. */
+    perInvocation?: boolean;
+    /** Separate grants for commands that name several origins. */
+    scopes?: string[];
+    webUrls?: URL[];
+    webOutboundTexts?: string[];
+    /** What a grant covers, for `ask`. Derived from the non-auto segments only. */
+    scope: string;
+    /** Populated for `refuse`: why, in a sentence the model can act on. */
+    reason?: string;
+    /** For `ask`: the allowlist rule that pre-approves every part of the command that needed asking. */
+    allowedBy?: string;
+}
+/**
+ * Classify one command line. Output redirection is refused outright unless the
+ * target provably writes nothing — `/dev/null`, or an fd duplication like
+ * `2>&1` — since a planner that writes files has stopped being a planner.
+ */
+declare function classifyCommand(command: string, opts?: CommandPolicyOptions): CommandClassification;
+
+/**
+ * Decides whether one out-of-envelope capability may run, and remembers the
+ * answer for the rest of the session.
+ *
+ * Grants are keyed on {@link ApprovalRequest.scope}, never on the concrete
+ * subject: approving a read of `/tmp/foo/a.log` grants `/tmp/foo/*`, and
+ * approving `az group list` grants `az group list`. Without that, a planner
+ * doing real research would prompt on every single call and the feature would
+ * be unusable.
+ *
+ * `mode` is the policy floor:
+ *   ask     consult the human channel; no channel means deny (headless, web)
+ *   allow   grant everything the tier system did not already refuse
+ *   deny    grant nothing beyond `preApproved` — the allowlist-only mode
+ *
+ * Note the ordering: `preApproved` is honored under every mode including
+ * `deny`, because it is an explicit operator decision rather than a default.
+ * Its entries are allowlist rules (see `plannerAllowlist.ts`), and both it and
+ * `mode` may be read afresh on every request, so a settings change applies to
+ * the next call.
+ */
+type ApprovalMode = 'ask' | 'allow' | 'deny';
+/**
+ * The configured mode. `auto` follows the autonomy level (ADR-0026): Guarded
+ * asks, Full runs the allowlist alone and asks nobody, so a planner in Full
+ * never waits on a person and never acts outside its standing approvals.
+ */
+type ApprovalModeSetting = ApprovalMode | 'auto';
+declare function effectiveApprovalMode(setting: ApprovalModeSetting, autonomous: boolean, kind?: ApprovalKind): ApprovalMode;
+/** A configured mode as written: `allowlist` is the user-facing name of `deny`, and anything unknown is `auto`. */
+declare function parseApprovalModeSetting(raw: string | undefined): ApprovalModeSetting;
+interface ApprovalPolicyOptions {
+    /** Read per request, for the kind being asked about. */
+    mode?: ApprovalMode | ((kind: ApprovalKind) => ApprovalMode);
+    autonomous?: () => boolean;
+    /** Allowlist entries granted up front from config (ADR-0026). */
+    preApproved?: readonly string[] | (() => readonly string[]);
+    /** The human channel. Absent means there is nobody to ask. */
+    ask?: (req: ApprovalRequest) => Promise<boolean>;
+    /** Called whenever a decision is reached, for surfacing in a UI or a log. */
+    onDecision?: (req: ApprovalRequest, granted: boolean, source: ApprovalSource) => void;
+}
+/**
+ * Why a request was decided as it was. The next four are refusals reached
+ * before the policy itself is consulted (ADR-0027's web-read guards), handed
+ * to {@link ApprovalPolicy.record} so they surface like any other decision:
+ * an `!` allowlist exclusion, the scheme and SSRF guard, the outbound secret
+ * check, and the per-turn web-read budget. `unsupported` comes after: an
+ * approved project MCP server the planner's runner version cannot give the
+ * planner as tools of their own (ADR-0028).
+ */
+type ApprovalSource = 'pre-approved' | 'remembered' | 'mode' | 'asked' | 'no-channel' | 'excluded' | 'guard' | 'secret' | 'budget' | 'unsupported';
+declare class ApprovalPolicy implements IApproval {
+    private readonly modeOf;
+    private readonly autonomousOf;
+    private readonly entriesOf;
+    private parsed;
+    private readonly asker?;
+    private readonly onDecision?;
+    private readonly granted;
+    private readonly refused;
+    /** One in-flight ask per scope: a parallel tool round must not prompt twice for the same thing. */
+    private readonly inFlight;
+    private generation;
+    constructor(opts?: ApprovalPolicyOptions);
+    request(req: ApprovalRequest): Promise<boolean>;
+    commandPolicy(): Pick<CommandPolicyOptions, 'autonomous' | 'approvalMode'>;
+    /**
+     * What `request` would answer without a person, for a caller that may never
+     * prompt (a research subagent): the same standing grants, remembered
+     * refusals and mode the interactive path uses, stopping at `ask`.
+     */
+    peek(req: ApprovalRequest): StandingDecision;
+    private standing;
+    /** Report a decision a guard reached before this policy was asked. */
+    record(req: ApprovalRequest, granted: boolean, source: ApprovalSource): void;
+    grantsUnasked({ kind, scope }: Pick<ApprovalRequest, 'kind' | 'scope'>): boolean;
+    /** The standing approvals, parsed from the entries in force now. */
+    allowlist(): PlannerAllowlist;
+    /** Scopes the user has granted this session — for display and for persistence. */
+    grantedScopes(): string[];
+    /** Drop every session-scoped decision. Called on session reset. */
+    reset(): void;
+}
+
 /**
  * The planner's single approval seam. Every capability that reaches beyond the
  * default read-only, in-workspace envelope — a path outside the workspace root,
@@ -17,11 +372,18 @@ import { z } from 'zod/v4';
 /**
  * `runner_tool` is a task runner's own tool request (ADR-0018, A1): it waits
  * for an answer as long as it takes, and never passes through the planner's
- * policy — the runner's mode already decided it needed asking.
+ * policy — the runner's mode already decided it needed asking. `mcp_tool` is
+ * a harness planner reaching for an MCP tool the user configured (ADR-0026),
+ * scoped to that one tool. `web_search` is scoped to the search provider, the
+ * party that receives every query (ADR-0027). `mcp_server` is starting an MCP
+ * server the repository declares for a planner, scoped to its definition
+ * (ADR-0028).
  */
-type ApprovalKind = 'external_path' | 'shell_command' | 'url_fetch' | 'runner_tool';
+type ApprovalKind = 'external_path' | 'shell_command' | 'url_fetch' | 'web_search' | 'mcp_tool' | 'mcp_server' | 'runner_tool';
 interface ApprovalRequest {
     kind: ApprovalKind;
+    /** Credentials, data and redirects need a fresh human answer for each invocation. */
+    perInvocation?: boolean;
     /** The concrete thing being asked about: an absolute path, a command line, a URL. */
     subject: string;
     /**
@@ -41,6 +403,14 @@ interface ApprovalRequest {
     taskId?: string;
     /** "Allow for this task" can be offered: the runner proposed its own session-scoped grant. */
     allowForTask?: boolean;
+    /**
+     * The allowlist rule the command classifier found covering every part of a
+     * `shell_command` that asks (ADR-0026). It settles `scope`, never the
+     * outside directories in `scopes`.
+     */
+    allowedBy?: string;
+    /** For `mcp_tool`: the tool's own name, without its server, which allowlist tool rules match. */
+    tool?: string;
 }
 /**
  * An answer, from whoever gives it — a person on any surface, or later the
@@ -61,8 +431,32 @@ declare function toApprovalDecision(answer: ApprovalAnswer): ApprovalDecision;
 declare function isGranted(decision: ApprovalDecision): boolean;
 declare function approvalScopes(request: ApprovalRequest): string[];
 declare function isRunnerApproval(request: ApprovalRequest): boolean;
+type StandingDecision = {
+    decision: 'allow' | 'deny';
+    source: 'pre-approved' | 'remembered' | 'mode';
+} | {
+    decision: 'deny';
+    source: 'excluded';
+} | {
+    decision: 'ask';
+    source: 'no-channel';
+};
 interface IApproval {
     request(req: ApprovalRequest): Promise<boolean>;
+    /** The standing approvals a command is classified against, when this approval has any (ADR-0026). */
+    allowlist?(): PlannerAllowlist;
+    commandPolicy?(): Pick<CommandPolicyOptions, 'autonomous' | 'approvalMode'>;
+    /** Surface a decision reached before `request` was called, as `request`'s own are. */
+    record?(req: ApprovalRequest, granted: boolean, source: ApprovalSource): void;
+    /**
+     * Resolve a request without a person (ADR-0027): `allow` when it is already
+     * granted or the mode allows without asking, `deny` when a refusal is
+     * remembered or the mode forbids, `ask` when it would still need a prompt. A
+     * background research subagent never prompts, so `ask` means refused.
+     */
+    peek?(req: ApprovalRequest): StandingDecision;
+    /** Whether `request` would grant this scope now without asking anyone. Nothing is asked or recorded. */
+    grantsUnasked?(req: Pick<ApprovalRequest, 'kind' | 'scope'>): boolean;
 }
 /** Denies everything. The safe default when a surface wires no approval channel. */
 declare const DENY_ALL: IApproval;
@@ -92,6 +486,15 @@ declare const listRunnersInput: z.ZodObject<{}, z.core.$strip>;
 declare const listModelsInput: z.ZodObject<{
     runner: z.ZodString;
 }, z.core.$strip>;
+declare const runCommandInput: z.ZodObject<{
+    command: z.ZodString;
+}, z.core.$strip>;
+declare const fetchInput: z.ZodObject<{
+    url: z.ZodString;
+}, z.core.$strip>;
+declare const webSearchInput: z.ZodObject<{
+    query: z.ZodString;
+}, z.core.$strip>;
 declare const loadSkillInput: z.ZodObject<{
     name: z.ZodString;
 }, z.core.$strip>;
@@ -186,6 +589,9 @@ type CheckpointArgs = z.infer<typeof checkpointInput>;
 type ListRunnersArgs = z.infer<typeof listRunnersInput>;
 type ListModelsArgs = z.infer<typeof listModelsInput>;
 type LoadSkillArgs = z.infer<typeof loadSkillInput>;
+type RunCommandArgs = z.infer<typeof runCommandInput>;
+type FetchArgs = z.infer<typeof fetchInput>;
+type WebSearchArgs = z.infer<typeof webSearchInput>;
 type SubmitPlanArgs = z.infer<typeof submitPlanInput>;
 type EditPlanArgs = z.infer<typeof editPlanInput>;
 type TaskQueryArgs = z.infer<typeof taskQueryInput>;
@@ -220,6 +626,9 @@ interface TaskToolHandler {
 }
 interface PlannerToolHandler {
     loadSkill?: Run<LoadSkillArgs>;
+    runCommand?: Run<RunCommandArgs>;
+    fetch?: Run<FetchArgs>;
+    webSearch?: Run<WebSearchArgs>;
     listRunners?: Run<ListRunnersArgs>;
     listModels?: Run<ListModelsArgs>;
     submitPlan?: Run<SubmitPlanArgs>;
@@ -263,11 +672,19 @@ interface TaskTokenScope {
 }
 interface PlannerTokenScope {
     sessionId: string;
+    /**
+     * Planner tools this token neither lists nor serves, by their names on the
+     * server: the ones a runner carries natively instead (ADR-0027), which a
+     * model would otherwise pick over its own.
+     */
+    hidden?: readonly string[];
 }
 /** Where a runner reaches the server and what it presents there. Never put either half in a prompt. */
 interface McpCredential {
     url: string;
     token: string;
+    /** The planner tools the token hides ({@link PlannerTokenScope.hidden}), so the runner is told of and pre-allows only what it is served. */
+    hidden?: readonly string[];
 }
 declare class OrdewellMcpServer {
     private readonly grants;
@@ -281,6 +698,8 @@ declare class OrdewellMcpServer {
     get url(): string | undefined;
     issueTaskToken(scope: TaskTokenScope, handler?: TaskToolHandler): Promise<McpCredential>;
     issuePlannerToken(scope: PlannerTokenScope, handler?: PlannerToolHandler): Promise<McpCredential>;
+    /** Every token still good here: secrets the outbound check keeps out of a URL (ADR-0027). */
+    heldTokens(): string[];
     /** Refuse every later request carrying `token`, and abort the calls it has in flight. */
     revoke(token: string): void;
     dispose(): Promise<void>;
@@ -297,6 +716,8 @@ interface McpClientConfig {
     name: typeof ORDEWELL_MCP_SERVER_NAME;
     url: string;
     headers: Record<string, string>;
+    /** Planner tools the token hides: a runner must neither pre-allow nor mention them. */
+    hidden?: readonly string[];
 }
 /**
  * The one shape every runner adapter renders its own MCP configuration from.
@@ -318,6 +739,23 @@ interface OwnerOnlyFile {
  */
 declare function ownerOnlyConfigFile(fileName: string, contents: string): OwnerOnlyFile;
 
+/**
+ * One MCP server a repository declares. `definition` is the entry as
+ * Ordewell parsed it, in the runner's own shape: an approved server is
+ * handed to the runner as exactly this, never re-read from the file.
+ */
+interface ProjectMcpServer {
+    name: string;
+    /** The file that declares it, relative to the workspace. */
+    source: string;
+    transport: 'stdio' | 'remote';
+    /** What would run, as written: the command line, or the URL. */
+    target: string;
+    /** The variables it sets, or the headers it sends, by name. */
+    names: string[];
+    definition: Record<string, unknown>;
+}
+
 /**
  * The harness-planner transport contract (ADR-0009).
  *
@@ -400,15 +838,17 @@ type AgentEvent =
     digest: string;
 }
 /**
- * The agent asked to do something its mode does not cover. A planner always
- * auto-denies it (T1) — a planner that can mutate is not a planner — and the
- * adapter answers so the turn does not hang. A task's request stays open
- * until {@link TaskModeAgentAdapter.answerPermission} (ADR-0018, A1).
+ * The agent asked to do something its mode does not cover. Without
+ * `decided` the request stays open until {@link AgentAdapter.answerPermission}:
+ * a task's for a person (ADR-0018, A1), a planner's for the planner's
+ * envelope (ADR-0026). An adapter that cannot hold a planner's request open
+ * denies it itself and says so in `decided`, so the turn does not hang.
  *
  * `input` and `suggestions` are the raw request; `suggestions` are the
  * agent's own session-scoped grants, what "Allow for this task" answers with.
- * `decided` marks a request the task's mode already answered — the adapter
- * replied as the manifest says that mode does — so it is shown, never asked.
+ * `decided` marks a request already answered — by the adapter, as the
+ * manifest says the task's mode does, or as a denial — so it is shown, never asked.
+ * `ask` is what a planner's open request is for, in the envelope's terms.
  */
  | {
     type: 'permission_request';
@@ -419,6 +859,7 @@ type AgentEvent =
     suggestions?: unknown[];
     toolUseId?: string;
     decided?: ApprovalDecision;
+    ask?: PlannerAsk;
 }
 /** The agent withdrew an open request — an interrupt cancels the call it was for. It takes no answer now. */
  | {
@@ -468,6 +909,41 @@ type AgentEvent =
     type: 'error';
     message: string;
 };
+/**
+ * What a planner's permission request is for, read from the runner's own
+ * request by its adapter, so one envelope decides it whichever runner asked
+ * (ADR-0026). `other` is anything the envelope never grants a planner.
+ */
+type PlannerAsk = 
+/** `scope` is the tool's full name as the runner reports it; `tool` its own name, without the server. */
+{
+    kind: 'mcp';
+    scope: string;
+    tool: string;
+    server?: string;
+} | {
+    kind: 'fetch';
+    url: string;
+}
+/**
+ * A search the runner carries itself, at `provider`; Ordewell decides it, it does not run it.
+ * `providerLabel` names that party in the approval.
+ */
+ | {
+    kind: 'search';
+    query: string;
+    provider: string;
+    providerLabel?: string;
+} | {
+    kind: 'path';
+    path: string;
+    directory: boolean;
+}
+/** `note` is why, for a tool the runner knows the planner must not use, in place of the envelope's generic refusal. */
+ | {
+    kind: 'other';
+    note?: string;
+};
 interface AgentStartCommon {
     /** Workspace root. The agent works from here and, in read-only mode, cannot leave it. */
     cwd: string;
@@ -489,6 +965,20 @@ interface PlannerStartOptions extends AgentStartCommon {
     effort?: string;
     /** The Ordewell MCP server to inject, pre-authorized (ADR-0022). Only for an adapter with {@link AgentAdapter.mcpAttached}. */
     mcp?: McpClientConfig;
+    /**
+     * Whether the runner's own search is on, for a runner whose search raises
+     * no permission request and is set on or off when its session starts
+     * (ADR-0027). Decided once, before the planner token is issued, so the
+     * tools the token serves and the session's config cannot disagree. Absent
+     * means off.
+     */
+    nativeSearch?: boolean;
+    /**
+     * The repository's own MCP servers this planner may start, as approved
+     * (ADR-0028). The runner is launched without the repository's config, so
+     * these are the only ones it gets, and each is handed over as parsed.
+     */
+    projectServers?: ProjectMcpServer[];
 }
 /**
  * What a runner manifest says the task's mode and effort mean (ADR-0001),
@@ -556,6 +1046,18 @@ interface AgentAdapter {
      * adapter that cannot inject the server at all, which cannot run tasks.
      */
     mcpAttached?(): Promise<boolean>;
+    /**
+     * The approved project servers (ADR-0028) this runner started but cannot
+     * give the planner as tools of their own, known once `start` resolved.
+     * Absent on an adapter that gives the planner every one it starts.
+     */
+    unusableProjectServers?(): ProjectMcpServer[];
+    /**
+     * Answer an open `permission_request`. False when the id is not open — it
+     * was answered, cancelled, or never asked. Absent on an adapter that leaves
+     * no planner request open.
+     */
+    answerPermission?(id: string, decision: ApprovalDecision): boolean;
 }
 /** What an adapter adds to run a task rather than a planner (ADR-0018). */
 interface TaskModeAgentAdapter extends AgentAdapter {
@@ -586,10 +1088,6 @@ interface TaskModeAgentAdapter extends AgentAdapter {
      * mid-turn.
      */
     steer?(id: string, text: string): Promise<boolean>;
-    /**
-     * Answer an open `permission_request`. False when the id is not open — it
-     * was answered, cancelled, or never asked.
-     */
     answerPermission(id: string, decision: ApprovalDecision): boolean;
 }
 type SpawnFn = (command: string, args: string[], options: {
@@ -749,53 +1247,6 @@ interface RunnerEntry {
     manifest: RunnerManifest;
 }
 
-/**
- * Decides whether one out-of-envelope capability may run, and remembers the
- * answer for the rest of the session.
- *
- * Grants are keyed on {@link ApprovalRequest.scope}, never on the concrete
- * subject: approving a read of `/tmp/foo/a.log` grants `/tmp/foo/*`, and
- * approving `az group list` grants `az group`. Without that, a planner doing
- * real research would prompt on every single call and the feature would be
- * unusable.
- *
- * `mode` is the policy floor:
- *   ask     consult the human channel; no channel means deny (headless, web)
- *   allow   grant everything the tier system did not already refuse
- *   deny    grant nothing beyond `preApproved`
- *
- * Note the ordering: `preApproved` is honored under every mode including
- * `deny`, because it is an explicit operator decision rather than a default.
- */
-type ApprovalMode = 'ask' | 'allow' | 'deny';
-interface ApprovalPolicyOptions {
-    mode?: ApprovalMode;
-    /** Scopes granted up front from config. A trailing `*` matches by prefix. */
-    preApproved?: string[];
-    /** The human channel. Absent means there is nobody to ask. */
-    ask?: (req: ApprovalRequest) => Promise<boolean>;
-    /** Called whenever a decision is reached, for surfacing in a UI or a log. */
-    onDecision?: (req: ApprovalRequest, granted: boolean, source: ApprovalSource) => void;
-}
-type ApprovalSource = 'pre-approved' | 'remembered' | 'mode' | 'asked' | 'no-channel';
-declare class ApprovalPolicy implements IApproval {
-    private readonly mode;
-    private readonly preApproved;
-    private readonly asker?;
-    private readonly onDecision?;
-    private readonly granted;
-    private readonly refused;
-    /** One in-flight ask per scope: a parallel tool round must not prompt twice for the same thing. */
-    private readonly inFlight;
-    private generation;
-    constructor(opts?: ApprovalPolicyOptions);
-    request(req: ApprovalRequest): Promise<boolean>;
-    /** Scopes the user has granted this session — for display and for persistence. */
-    grantedScopes(): string[];
-    /** Drop every session-scoped decision. Called on session reset. */
-    reset(): void;
-}
-
 interface CatalogModel {
     id: string;
     name: string;
@@ -961,13 +1412,18 @@ interface IConfig {
     conflictRepairAttempts: number;
     /**
      * What to do when planner research reaches outside its default envelope — an
-     * out-of-workspace path, or a shell command beyond the auto-allowed read-only
-     * set. `ask` prompts the user (and denies where no surface can prompt, such as
-     * headless runs); `allow` and `deny` skip the prompt entirely.
+     * out-of-workspace path, a shell command beyond the auto-allowed read-only
+     * set, an MCP tool. `ask` prompts the user (and denies where no surface can
+     * prompt, such as headless runs); `allow` and `deny` skip the prompt
+     * entirely; `auto` follows {@link autonomousMode} (ADR-0026).
      */
-    approvalMode: ApprovalMode;
-    /** Scopes granted up front, so CI and power users never see a prompt. Trailing `*` matches by prefix. */
+    approvalMode: ApprovalModeSetting;
+    /** Allowlist entries granted up front, beside the defaults (ADR-0026, `plannerAllowlist.ts`). */
     approvalPreApproved: string[];
+    /** Whether the built-in allowlist of read-only command families and MCP tools applies. */
+    approvalDefaults: boolean;
+    /** How many fetches and searches one planner turn may make (ADR-0027). User-only, like the approval settings. */
+    webReadBudget: number;
     /** Get the base URL for an OpenAI-compatible provider. */
     getProviderBaseUrl(provider: AiProvider): string;
     /** Get the API key for a provider. */
@@ -1162,4 +1618,4 @@ interface IRunner {
     activeCount: number;
 }
 
-export { type RunnerManifest as $, type AgentAdapter as A, type McpToolReply as B, type CatalogModel as C, DENY_ALL as D, type EditPlanArgs as E, type FetchAllProviderModelsOptions as F, ModelCatalog as G, type ModelShortcut as H, type IApproval as I, ORDEWELL_MCP_PATH as J, ORDEWELL_MCP_SERVER_NAME as K, LineBuffer as L, type McpClientConfig as M, type OrchestratorOption as N, ORCHESTRATOR_SHORTCUTS as O, OrdewellMcpServer as P, type OwnerOnlyFile as Q, PLANNER_TOOLS as R, type PlannerStartOptions as S, type PlannerTokenScope as T, type PlannerToolHandler as U, type ProviderCredentialSource as V, type ProviderModelLists as W, type ProviderModelsResult as X, type QueuedTaskMessage as Y, type RunnerEntry as Z, type RunnerFeatures as _, type AgentAdapterFactory as a, type RunnerMode as a0, type RunnerModelDiscovery as a1, RunnerRegistry as a2, type SpawnFn as a3, type StructuredEvent as a4, type StructuredTurnEnd as a5, type SubmitPlanArgs as a6, TASK_COMPLETE_TOOL as a7, TASK_TOOLS as a8, type TaskCompleteArgs as a9, type TaskModeAgentAdapter as aa, TaskModeUnsupportedError as ab, type TaskOutputArgs as ac, type TaskQueryArgs as ad, type TaskRunnerFlags as ae, type TaskStartOptions as af, type TaskTokenScope as ag, type TaskToolHandler as ah, approvalScopes as ai, collectProviderCredentials as aj, enabledRunners as ak, fetchAllProviderModels as al, isGranted as am, isRunnerApproval as an, knownModelId as ao, mcpClientConfig as ap, ownerOnlyConfigFile as aq, resolveModelShortcut as ar, resolveProvider as as, sharedMcpServer as at, toApprovalDecision as au, toOrchestratorOptions as av, type AgentEvent as b, type AgentProcessDeps as c, type AgentStartOptions as d, type AiProvider as e, type AllProviderModels as f, type ApprovalAnswer as g, type ApprovalDecision as h, type ApprovalKind as i, type ApprovalMode as j, ApprovalPolicy as k, type ApprovalPolicyOptions as l, type ApprovalRequest as m, type ApprovalSource as n, type CheckpointAnswer as o, type CheckpointArgs as p, type DiscoveryCommand as q, type IConfig as r, type IRunner as s, type IRunnerSession as t, type ListModelsArgs as u, type ListRunnersArgs as v, type LoadSkillArgs as w, type McpCredential as x, type McpTool as y, type McpToolContext as z };
+export { type PlannerTokenScope as $, AUTO_COMMANDS as A, type ListModelsArgs as B, type CatalogModel as C, DEFAULT_PLANNER_ALLOWLIST as D, type EditPlanArgs as E, type FetchAllProviderModelsOptions as F, GIT_READONLY_SUBCOMMANDS as G, type ListRunnersArgs as H, type IApproval as I, type LoadSkillArgs as J, type McpCredential as K, LineBuffer as L, type McpClientConfig as M, type McpTool as N, type McpToolContext as O, type McpToolReply as P, ModelCatalog as Q, type ModelShortcut as R, ORCHESTRATOR_SHORTCUTS as S, ORDEWELL_MCP_PATH as T, ORDEWELL_MCP_SERVER_NAME as U, type OrchestratorOption as V, OrdewellMcpServer as W, type OwnerOnlyFile as X, PLANNER_TOOLS as Y, type PlannerAllowlist as Z, type PlannerStartOptions as _, type AgentAdapter as a, type PlannerToolHandler as a0, type ProjectMcpServer as a1, type ProviderCredentialSource as a2, type ProviderModelLists as a3, type ProviderModelsResult as a4, type QueuedTaskMessage as a5, REFUSED_COMMANDS as a6, type ResearchShell as a7, type ResearchShellDeps as a8, type RunCommandArgs as a9, collectProviderCredentials as aA, commandAllowedBy as aB, effectiveApprovalMode as aC, enabledRunners as aD, fetchAllProviderModels as aE, isGranted as aF, isRunnerApproval as aG, knownModelId as aH, mcpClientConfig as aI, ownerOnlyConfigFile as aJ, parseAllowlist as aK, parseApprovalModeSetting as aL, researchShellWarning as aM, researchToolsPath as aN, resolveModelShortcut as aO, resolveProvider as aP, resolveResearchShell as aQ, scopeAllowed as aR, sharedMcpServer as aS, toApprovalDecision as aT, toOrchestratorOptions as aU, toolAllowed as aV, type RunnerEntry as aa, type RunnerFeatures as ab, type RunnerManifest as ac, type RunnerMode as ad, type RunnerModelDiscovery as ae, RunnerRegistry as af, type ShellDialect as ag, type SpawnFn as ah, type StandingDecision as ai, type StructuredEvent as aj, type StructuredTurnEnd as ak, type SubmitPlanArgs as al, TASK_COMPLETE_TOOL as am, TASK_TOOLS as an, type TaskCompleteArgs as ao, type TaskModeAgentAdapter as ap, TaskModeUnsupportedError as aq, type TaskOutputArgs as ar, type TaskQueryArgs as as, type TaskRunnerFlags as at, type TaskStartOptions as au, type TaskTokenScope as av, type TaskToolHandler as aw, approvalScopes as ax, classifyCommand as ay, clearResearchShellCache as az, type AgentAdapterFactory as b, type AgentEvent as c, type AgentProcessDeps as d, type AgentStartOptions as e, type AiProvider as f, type AllProviderModels as g, type ApprovalAnswer as h, type ApprovalDecision as i, type ApprovalKind as j, type ApprovalMode as k, type ApprovalModeSetting as l, ApprovalPolicy as m, type ApprovalPolicyOptions as n, type ApprovalRequest as o, type ApprovalSource as p, type CheckpointAnswer as q, type CheckpointArgs as r, type CommandClassification as s, type CommandTier as t, type CommandWords as u, DENY_ALL as v, type DiscoveryCommand as w, type IConfig as x, type IRunner as y, type IRunnerSession as z };