@ordewell/core 0.9.0 → 0.9.1

package/dist/{IFileSystem-DpaaFdit.d.ts → IFileSystem-BjiyCQ8O.d.ts}

@@ -1,4 +1,4 @@
-import { I as IApproval } from './IRunner-BiQio8gJ.js';
+import { I as IApproval } from './IRunner-Corods20.js';
 
 interface ToolOutcome {
     success: boolean;
@@ -71,6 +71,8 @@ interface IFileSystem {
      * test doubles stay small; every adapter extending `BaseFileSystem` has it.
      */
     setApproval?(approval: IApproval): void;
+    /** Held credentials read live by the outbound secret check. */
+    setOutboundSecrets?(secrets: () => Iterable<string>): void;
 }
 
 export { type FindSymbolOptions as F, GREP_DEFAULT_HEAD_LIMIT as G, type IFileSystem as I, type ReadFileOpts as R, SEARCH_EXCLUSIONS as S, type ToolOutcome as T, type GlobOptions as a, type GrepOptions as b, type GrepOutputMode as c };

package/dist/{IFileSystem-_m7HdoxJ.d.mts → IFileSystem-Cy-TAWvu.d.mts}

@@ -1,4 +1,4 @@
-import { I as IApproval } from './IRunner-CxiymkP_.mjs';
+import { I as IApproval } from './IRunner-D6YfbmHn.mjs';
 
 interface ToolOutcome {
     success: boolean;
@@ -71,6 +71,8 @@ interface IFileSystem {
      * test doubles stay small; every adapter extending `BaseFileSystem` has it.
      */
     setApproval?(approval: IApproval): void;
+    /** Held credentials read live by the outbound secret check. */
+    setOutboundSecrets?(secrets: () => Iterable<string>): void;
 }
 
 export { type FindSymbolOptions as F, GREP_DEFAULT_HEAD_LIMIT as G, type IFileSystem as I, type ReadFileOpts as R, SEARCH_EXCLUSIONS as S, type ToolOutcome as T, type GlobOptions as a, type GrepOptions as b, type GrepOutputMode as c };

package/dist/{IRunner-BiQio8gJ.d.ts → IRunner-Corods20.d.ts}

@@ -20,7 +20,7 @@ import { z } from 'zod/v4';
  *   - 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://`, `mcp__` or a drive letter: matched against an approval's
+ *     `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.
  *
@@ -74,6 +74,289 @@ declare function scopeAllowed(list: PlannerAllowlist, scope: string): boolean;
  */
 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,
@@ -91,11 +374,16 @@ declare const DEFAULT_PLANNER_ALLOWLIST: readonly string[];
  * 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. `mcp_tool` is
  * a harness planner reaching for an MCP tool the user configured (ADR-0026),
- * scoped to that one tool.
+ * 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' | 'mcp_tool' | '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;
     /**
@@ -143,10 +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;
@@ -179,6 +489,12 @@ declare const listModelsInput: z.ZodObject<{
 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>;
@@ -274,6 +590,8 @@ 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>;
@@ -309,6 +627,8 @@ 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>;
@@ -352,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;
@@ -370,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>;
@@ -386,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.
@@ -407,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).
  *
@@ -575,12 +924,25 @@ type PlannerAsk =
 } | {
     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. */
@@ -603,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),
@@ -670,6 +1046,12 @@ 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
@@ -865,68 +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 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): 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 {
-    mode?: ApprovalMode | (() => ApprovalMode);
-    /** 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;
-}
-type ApprovalSource = 'pre-approved' | 'remembered' | 'mode' | 'asked' | 'no-channel';
-declare class ApprovalPolicy implements IApproval {
-    private readonly modeOf;
-    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>;
-    /** 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;
-}
-
 interface CatalogModel {
     id: string;
     name: string;
@@ -1102,6 +1422,8 @@ interface IConfig {
     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. */
@@ -1296,4 +1618,4 @@ interface IRunner {
     activeCount: number;
 }
 
-export { type ProviderModelsResult as $, type AgentAdapter as A, type McpCredential as B, type CatalogModel as C, DEFAULT_PLANNER_ALLOWLIST as D, type EditPlanArgs as E, type FetchAllProviderModelsOptions as F, type McpTool as G, type McpToolContext as H, type IApproval as I, type McpToolReply as J, ModelCatalog as K, LineBuffer as L, type McpClientConfig as M, type ModelShortcut as N, ORCHESTRATOR_SHORTCUTS as O, ORDEWELL_MCP_PATH as P, ORDEWELL_MCP_SERVER_NAME as Q, type OrchestratorOption as R, OrdewellMcpServer as S, type OwnerOnlyFile as T, PLANNER_TOOLS as U, type PlannerAllowlist as V, type PlannerStartOptions as W, type PlannerTokenScope as X, type PlannerToolHandler as Y, type ProviderCredentialSource as Z, type ProviderModelLists as _, type AgentAdapterFactory as a, type QueuedTaskMessage as a0, type RunCommandArgs as a1, type RunnerEntry as a2, type RunnerFeatures as a3, type RunnerManifest as a4, type RunnerMode as a5, type RunnerModelDiscovery as a6, RunnerRegistry as a7, type SpawnFn as a8, type StructuredEvent as a9, resolveModelShortcut as aA, resolveProvider as aB, scopeAllowed as aC, sharedMcpServer as aD, toApprovalDecision as aE, toOrchestratorOptions as aF, toolAllowed as aG, type StructuredTurnEnd as aa, type SubmitPlanArgs as ab, TASK_COMPLETE_TOOL as ac, TASK_TOOLS as ad, type TaskCompleteArgs as ae, type TaskModeAgentAdapter as af, TaskModeUnsupportedError as ag, type TaskOutputArgs as ah, type TaskQueryArgs as ai, type TaskRunnerFlags as aj, type TaskStartOptions as ak, type TaskTokenScope as al, type TaskToolHandler as am, approvalScopes as an, collectProviderCredentials as ao, commandAllowedBy as ap, effectiveApprovalMode as aq, enabledRunners as ar, fetchAllProviderModels as as, isGranted as at, isRunnerApproval as au, knownModelId as av, mcpClientConfig as aw, ownerOnlyConfigFile as ax, parseAllowlist as ay, parseApprovalModeSetting as az, 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, type ApprovalModeSetting as k, ApprovalPolicy as l, type ApprovalPolicyOptions as m, type ApprovalRequest as n, type ApprovalSource as o, type CheckpointAnswer as p, type CheckpointArgs as q, type CommandWords as r, DENY_ALL as s, type DiscoveryCommand as t, type IConfig as u, type IRunner as v, type IRunnerSession as w, type ListModelsArgs as x, type ListRunnersArgs as y, type LoadSkillArgs 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 };