@@ -14,6 +14,89 @@ The headless agent harness for CI, cron jobs, and container workflows.
1414- ** Declarative Permissions:** Per-tool allow/deny rules (` permission ` config); tools denied everywhere are stripped from the model request to save tokens.
1515- ** Skills & MCP:** Progressive skill loading (` --skill ` ) and first-class [ Model Context Protocol] ( https://modelcontextprotocol.io ) support.
1616
17+ ## Select work tools for one run
18+
19+ Use exact registered names to choose an independent work-tool allowlist:
20+
21+ ``` bash
22+ aictrl run --tools read,glob,grep " Find the configuration entry points"
23+ aictrl run --tools ' ' " Answer using only the supplied prompt"
24+ ```
25+
26+ Omitting ` --tools ` uses the final config's optional ` tool_allowlist ` preference;
27+ without either input, normal tools remain available. For example,
28+ ` "tool_allowlist": ["read", "grep"] ` sets a default, and ` [] ` selects no work
29+ tools. Later config sources replace the whole array, including an empty array.
30+ The CLI replaces that preference for the current invocation. It does not change
31+ the next invocation's default, including on reused or forked sessions.
32+
33+ Names are case-sensitive and exact: ` read ` , ` write ` , and ` edit ` are independent;
34+ no aliases or automatic dependencies are added. Exact duplicates are removed in
35+ first-seen order. Whitespace-only names, surrounding whitespace, empty comma
36+ elements and unknown or model/flag-unavailable names fail before model inference.
37+ A selected tool that permissions deny remains denied. Existing permission
38+ aliases, path checks and last-match rules still apply.
39+
40+ Start with a toolset that matches the task and the model's available catalog:
41+
42+ | Task | ` --tools ` value |
43+ | ------------------------------------- | --------------------------------- |
44+ | Review code | ` read,glob,grep ` |
45+ | Explain supplied code or a known file | ` read ` |
46+ | Fix code with an edit/write catalog | ` read,glob,grep,edit,write,bash ` |
47+ | Fix code with an apply_patch catalog | ` read,glob,grep,apply_patch,bash ` |
48+
49+ Use the fix variant supported by the selected model; unavailable names fail.
50+ Include ` bash ` only when the task needs shell commands such as tests. The review
51+ and explain examples select registered work tools; existing permission checks
52+ still apply.
53+
54+ The saved user invocation retains its resolved selection for continuation and
55+ compaction. When selection is active, delegated tasks (including resumed task
56+ sessions) inherit a ceiling from the parent's effective tools; child config,
57+ model and permissions can narrow it. Batch validates its whole group against the
58+ same request catalog before executing any call. Recursive Batch and MCP tools
59+ remain unsupported inside Batch. Custom tools retain their actual identity when
60+ replacing a built-in name. Explicit caller-directed command subtasks keep their
61+ existing Task authorization exception; an active selection still requires the
62+ eligible native Task tool to be selected, without adding permission allow rules.
63+
64+ ` StructuredOutput ` , invalid-call repair and LiteLLM's compatibility placeholder
65+ are protocol/control tools, outside the work allowlist. Schema mode still needs
66+ permission to call ` StructuredOutput ` ; selecting work tools never grants that
67+ permission. An empty work allowlist can therefore coexist with an explicitly
68+ permitted StructuredOutput protocol tool. Custom tools with protocol-like names
69+ remain work tools, except that an active output schema reserves the
70+ ` StructuredOutput ` wire name for the harness-created protocol tool. A custom
71+ ` StructuredOutput ` is selectable as work only outside schema mode.
72+
73+ Custom tools can use the optional typed ` context.selection ` facade to inspect
74+ ` names ` /` restricted ` , assert availability, or call
75+ ` await context.selection.execute("read", { filePath: "/path/to/file" }) ` .
76+ Dispatch is bound to the actual caller context, checks the same catalog and
77+ permissions before hooks, and validates captured registry parameters. Omitting a
78+ tool or denying it in permissions also prevents this supported nested dispatch.
79+ The facade and names are immutable; arbitrary plugin host code remains trusted.
80+
81+ Selection applies to harness-dispatched model work. Caller ` --file ` /` @file `
82+ attachments and configured command-template shell expansion are input preparation
83+ and keep their existing behavior. This is not an operating-system sandbox for
84+ selected Bash commands or arbitrary plugin host code. Independent debug-tool
85+ commands do not inherit ` run ` selection.
86+
87+ ** Attach:** this headless checkout has no owned server or verified server-side
88+ selection capability. Any explicit or locally configured selection, including an
89+ empty list, fails with ` --attach ` before receiver API calls, remote session
90+ creation/fork/prompt/command or model inference. An explicit CLI selector fails
91+ before configuration discovery. With the CLI selector omitted, read-only
92+ configuration discovery preserves normal config precedence and can fetch
93+ well-known configuration; this configuration HTTP is distinct from attach
94+ receiver calls. It performs no plugin/dependency setup, config rewrites, legacy
95+ TOML migration or token refresh. Invalid local configuration can therefore fail
96+ before attach. Valid configuration without a selector retains the existing
97+ attach transport and contents. Successful remote selection requires a future
98+ supporting receiver and is not provided by this option.
99+
17100## Automation Usage
18101
19102Aictrl is built to be used in non-interactive environments.
@@ -143,12 +226,12 @@ Aictrl reads config from `.aictrl/` (project) or `~/.config/aictrl/` (global).
143226
144227### Models
145228
146- | Provider | Env Var |
147- | ----------| ---------|
148- | Anthropic | ` ANTHROPIC_API_KEY ` |
149- | OpenAI | ` OPENAI_API_KEY ` |
229+ | Provider | Env Var |
230+ | ---------------- | -------------------------------------------------------------------- |
231+ | Anthropic | ` ANTHROPIC_API_KEY ` |
232+ | OpenAI | ` OPENAI_API_KEY ` |
150233| Google AI Studio | ` GOOGLE_GENERATIVE_AI_API_KEY ` , ` GEMINI_API_KEY ` or ` GOOGLE_API_KEY ` |
151- | OpenRouter | ` OPENROUTER_API_KEY ` |
234+ | OpenRouter | ` OPENROUTER_API_KEY ` |
152235
153236Use ` --variant ` to select provider-specific reasoning effort. For OpenAI-compatible
154237Ollama models, ` --variant none ` sends ` reasoning_effort: "none" ` to disable
0 commit comments