Skip to content

Commit 380e994

Browse files
authored
Merge 46f98d5 into 4e56b02
2 parents 4e56b02 + 46f98d5 commit 380e994

25 files changed

Lines changed: 6828 additions & 383 deletions

‎packages/cli/README.md‎

Lines changed: 88 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -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

19102
Aictrl 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

153236
Use `--variant` to select provider-specific reasoning effort. For OpenAI-compatible
154237
Ollama models, `--variant none` sends `reasoning_effort: "none"` to disable

‎packages/cli/src/cli/cmd/generate.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import type { CommandModule } from "yargs"
22
import z from "zod"
3+
import { Config } from "@/config/config"
34
import { MessageV2 } from "@/session/message-v2"
45
import { Session } from "@/session"
56
import { SessionPrompt } from "@/session/prompt"
@@ -16,6 +17,8 @@ export const GenerateCommand = {
1617
registry.add(ProviderTermination.Info, { id: "ProviderTermination" })
1718
registry.add(MessageV2.Format, { id: "OutputFormat" })
1819
registry.add(MessageV2.Assistant, { id: "AssistantMessage" })
20+
registry.add(MessageV2.User, { id: "UserMessage" })
21+
registry.add(Config.Info, { id: "Config" })
1922
registry.add(
2023
z.object({
2124
type: z.literal(Session.Event.StructuredOutput.type),

‎packages/cli/src/cli/cmd/run.ts‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
import { outputSchema, outputResult, OUTPUT_SCHEMA_CONFIG, OUTPUT_CONFIG_EXIT, OUTPUT_FAILED_EXIT } from "./run.output"
2+
import { ToolSelection } from "../../tool/selection"
3+
import { Config } from "../../config/config"
24
import { OutputSchema } from "@/session/output-schema"
35
import type { Argv } from "yargs"
46
import path from "path"
@@ -375,6 +377,12 @@ export const RunCommand = cmd({
375377
.strictOptions()
376378
.strictCommands(false)
377379
.parserConfiguration({ "populate--": true, "parse-positional-numbers": false })
380+
.option("tools", {
381+
type: "string",
382+
nargs: 1,
383+
describe:
384+
"exact comma-separated work-tool names; use an empty string for no work tools (permissions still apply)",
385+
})
378386
.option("command", {
379387
describe: "the command to run, use message for args",
380388
type: "string",
@@ -488,6 +496,27 @@ export const RunCommand = cmd({
488496
process.exit(exit)
489497
}
490498

499+
const requested = args.tools
500+
if (requested !== undefined && typeof requested !== "string") {
501+
await fail(
502+
"Use --tools once with one comma-separated argument (for example, --tools read,bash).",
503+
"INVOCATION_INVALID_ARGUMENTS",
504+
)
505+
}
506+
const toolAllowlist =
507+
requested === undefined
508+
? undefined
509+
: await Promise.resolve()
510+
.then(() => ToolSelection.parse(requested))
511+
.catch((error) => fail(error.message, "INVOCATION_INVALID_ARGUMENTS"))
512+
513+
if (args.attach && requested !== undefined) {
514+
await fail(
515+
"Work-tool selection is not supported with --attach: this client cannot verify server-side enforcement. Remove --tools or run locally.",
516+
"INVOCATION_INVALID_ARGUMENTS",
517+
)
518+
}
519+
491520
if (args.share === true) {
492521
await fail("--share was removed: session sharing is no longer supported", "INVOCATION_INVALID_ARGUMENTS")
493522
}
@@ -1145,6 +1174,7 @@ export const RunCommand = cmd({
11451174
if (args.command) {
11461175
const opts = {
11471176
agent,
1177+
toolAllowlist,
11481178
model: args.model,
11491179
command: args.command,
11501180
arguments: { argv: normalized.argv, ...(stdin !== undefined ? { stdin } : {}) },
@@ -1157,6 +1187,7 @@ export const RunCommand = cmd({
11571187
const model = args.model ? Provider.parseModel(args.model) : undefined
11581188
const opts = {
11591189
agent,
1190+
toolAllowlist,
11601191
model,
11611192
variant: args.variant,
11621193
parts: [...files, { type: "text", text: message }],
@@ -1199,6 +1230,14 @@ export const RunCommand = cmd({
11991230

12001231
invocation.phase("bootstrap")
12011232
if (args.attach) {
1233+
// This checkout has no receiver/capability contract that can enforce selection.
1234+
const configured = await invocation.guard(() => Config.readToolSelection(process.cwd()))
1235+
if (configured !== undefined) {
1236+
await fail(
1237+
"Work-tool selection is not supported with --attach: this client cannot verify server-side enforcement. Remove --tools and local tool_allowlist or run locally.",
1238+
"INVOCATION_INVALID_ARGUMENTS",
1239+
)
1240+
}
12021241
return await invocation.run(() => execute(createAictrlClient({ baseUrl: args.attach, directory })))
12031242
}
12041243

@@ -1234,6 +1273,7 @@ export const RunCommand = cmd({
12341273
sessionID: opts.sessionID,
12351274
parts: opts.parts,
12361275
agent: opts.agent,
1276+
toolAllowlist: opts.toolAllowlist,
12371277
model: opts.model,
12381278
variant: opts.variant,
12391279
...(opts.format ? { format: opts.format } : {}),
@@ -1245,6 +1285,7 @@ export const RunCommand = cmd({
12451285
command: opts.command,
12461286
arguments: opts.arguments ?? "",
12471287
agent: opts.agent,
1288+
toolAllowlist: opts.toolAllowlist,
12481289
model: opts.model,
12491290
variant: opts.variant,
12501291
...(opts.format ? { format: opts.format } : {}),

0 commit comments

Comments
 (0)