Directive Index¶

Agent Configuration¶

Directive	Scope and contract
`> adapter: pydantic`	Select framework adapter: `pydantic`, `dspy`, or `langchain`
`> agent: codex`	Select harness: `claude`, `codex`, or `acp`
`> agent:` / `acp: command`	Select ACP and embed its stdio command
`> model: value`	Set plain or Python-evaluated model identifier
`> effort: level`	Set `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`
`> system: text`	Replace active instructions; block form joins lines
`> settings:`	Merge adapter settings by key
`> history: enabled\\|disabled`	Enable or disable scoped conversation continuity
`> history:`	Configure history ownership and native compaction settings
`> artifacts:`	Configure scoped large-value storage and compact references
`> codemode: enabled\\|disabled`	Enable or disable scoped tool discovery and sandboxed tool execution
`> codemode:`	Configure CodeMode discovery, execution and resource limits
`> approval: allow`, `deny`, or handler	Set lexical tool approval policy
`> hooks: enabled\\|disabled`	Enable or disable inherited lexical lifecycle handlers
`> hooks:`	Register handlers for named agent lifecycle events
`> mcp:`	Append one MCP server specification
`> use: name`	Register a tool or apply a profile
`> skills: enabled\\|disabled`	Configure scoped skill discovery
`> use:`	Register an indented list of procedure/Python tools

Framework and harness selection are mutually exclusive in one state. Literal names are statically validated; backtick expressions defer validation to runtime. Adapter settings unsupported by the selected backend are filtered or rejected according to that adapter's contract.

A directive block has one body shape. Configuration directives contain unprefixed name: value subsettings; composite directives such as > profile: contain >-prefixed subdirectives. Kedi does not mix both forms in one body.

> artifacts: fields are enabled, query_artifacts, store, path, threshold, ttl, idle_ttl, preview_chars, read_max_chars, session_quota, max_artifacts, and cleanup_interval. The policy is lexical and enabled by default. Artifact querying is separately disabled by default and accepts query_artifacts: enabled|disabled. See Tool Artifacts.

The expanded > history: form contains only subsettings. It requires enabled: true|false and accepts compaction_mode: native|disabled plus an optional positive compaction_threshold. Compaction is history lifecycle policy, not a model setting. See Caching and Conversation History.

> hooks: fields are user_prompt_submit, pre_tool_use, post_tool_use, and post_tool_use_failure. Each value is a Python callable or a sequence of callables. See Agent Lifecycle Hooks.

> mcp: fields:

> mcp:
    name: project_docs
    transport: stdio
    command: uv
    args: `["run", "docs-server"]`
    env: `{"LOG_LEVEL": "warning"}`
    cwd: .

Network transports use url instead of command/args. Valid normalized transports are documented in MCP Servers.

Profiles and Delegation¶

Directive	Contract
`> profile: name:`	Define a reusable agent state
`> subagent: child`	Permit one direct child profile
`> max_agents: N`	Bound descendant starts for one invocation
`> workflow: delegate\\|dynamic`	Select direct or sandboxed dynamic child orchestration
`> output: Type`	Declare a profile's default structured child result; an explicit child-call `final_schema` overrides it

A profile body may contain adapter or agent selection, model, effort, system, settings, approval, hooks, history, skills, CodeMode, artifact policy, MCP, tools, child profiles, descendant budget, workflow mode, and output type. See Profiles and Composition for the member-specific merge rules. Defining or applying a profile is configuration, not a model invocation.

> subagent:, > max_agents:, and > workflow: are profile members rather than arbitrary runtime spawn commands. delegate is the default. dynamic requires at least one direct child and exposes run_workflow instead of the delegation lifecycle tools. Forward child references are valid; unknown children, cycles, nonpositive budgets, duplicate workflow modes, and unsupported adapter capabilities fail.

Modules and Packages¶

Directive	Contract
`> import: module/path`	Import all explicitly exported names
`> import: module/path:`	Import only listed exported names
`> export:`	Export listed top-level procedures, types, values, or profiles
`> export: *`	Export all public names not starting with `_`
`> package: name:`	Declare metadata in `package.kedi` only

Imports are relative to their source file before bundled and installed-package fallbacks. Selective imports bind names directly, not under a namespace. Modules without an export directive expose nothing.

> package: supports author, contact, version, source, python, license, and one python_dependencies: list. The manifest must contain no executable statements.

Tests and Evaluation¶

Directive	Parent	Contract
`> case: name:`	`@test:`	One Python assertion block
`> data: name:`	`@eval:`	Training/fallback-eval iterable
`> test_data: name:`	`@eval:`	Matching held-out iterable
`> metric: name(dataset):`	`@eval:`	One score function for the suite

Cases run in source order and failures do not stop later cases. Eval suites allow one metric. --eval prefers same-named test data, while optimization always trains on data and validates with matching test data.

Optimization and Generation¶

@classify(text: str) -> str:
  > optimize: classification_prompt:
    >> The text <text> belongs to the [label] category.
  = `label`

@generated_slug(value: str) -> str:
  > auto:
    Implement deterministic slug generation for <value>.

> optimize: span_name: owns one model template whose optimized artifact key is the containing procedure plus span name. Every optimized procedure needs a same-named eval suite with training data and a metric.

> auto: requests generated procedure implementation and tests. Codegen uses a separate agent/model configuration and stores generated source in program.cache.kedi.

Both directive bodies accept explicit >> or legacy bare template lines. The entire body remains one newline-joined model call; the old syntax does not imply one request per line.

Placement and Capture¶

Agent directives at top level are captured by procedures defined afterward. Directives in a procedure affect subsequent calls in that invocation and are restored on exit. Profile application follows the same lexical rule.

Unknown directives, invalid placement, duplicate singleton members, malformed blocks, or wrong directive kinds are errors rather than ignored configuration.